Create and update entities

Create or update a requirement, architecture, standard, plan, milestone, or task from a markdown file when an MCP tool call cannot carry the body.

MCP is the normal agent write. Use orkai create and orkai update when the body is large, when a script should write the file, or when the client rejects the tool payload. Do not shrink the body. Do not drop fields. The body is the file, not an argument.

knowledge: on orkai index is repo sync, not this command. See Projects & indexing.

Commands

Types are singular. Each one maps to an MCP tool:

orkai create <type> --path <file.md> [--category-id <id>] [--name <name>]
orkai update <type> --id <id> [--path <file.md>]
orkai create <type> --help

There is no --text flag. --path - reads stdin. The flag list for the installed binary is orkai create <type> --help.

Minimal file

Flags override frontmatter. name comes from --name or frontmatter name. Never from the filename.

---
name: Improve checkout
---

What and why. This body is the entity text.

Category, first hit wins:

1. --category-id
2. frontmatter category_id
3. .orkai.yaml project.category_id

If none exist, the command fails.

Create and update

orkai create requirement --path requirement.md --category-id <category-id> --json
orkai update requirement --id <id> --path requirement.md --json

A task can set its parent and work fields on create. Parent ids and --references are create-only.

orkai create task --path task.md --milestone-id <milestone-id> --workflow-id <workflow-id> --model provider/model --json
orkai update task --id <id> --path task.md --json

Output

The human line is created requirement <full-id> or updated requirement <full-id>. --json prints id, name, type, and version. version is a number.

Verify with orkai get <id> --content.

Errors

Missing name, missing category, a bad status, and update with --plan-id all fail the same way. The CLI prints what is wrong, the fix, an example file, and the equivalent command. It does not drop a forbidden flag quietly.

Limits

There is no --text flag. If the daemon rejects the frame, the file is too big for service.protocol.maxMessageSizeBytes. Raise that limit or split the file. The CLI does not truncate.