Skip to main content
The CLI is the executable contract of an Agent Application. This page covers what every compatible runtime must implement when invoking application commands.

​
The CLI contract

Every Agent Application exposes a CLI entrypoint declared in APP.md as entry.command. The application’s CLI must:
  • Return machine-readable JSON to stdout by default
  • Return a non-zero exit code on failure
  • Return structured JSON errors on failure when possible
  • Use stable command names and stable entity identifiers
  • Treat human-readable output, if supported, as opt-in
Your runtime enforces this contract from the outside. You invoke the command, consume the JSON, and act on the exit code.

​
Invoking entry.command

Invoke entry.command from the package root, or a documented equivalent context. The entry.command field is a callable string — it may be a binary, a shell command, or a wrapper. The spec does not constrain the form, only that a compatible runtime can invoke it and receive structured JSON on stdout. For example, the Agentic To-Do application declares: 
entry:
  command: node app/cli.js
To run the list command: 
node app/cli.js list
node app/cli.js add "Write docs" --due-at 2026-04-05
node app/cli.js complete td_0001
Always invoke from the package root so relative paths inside the application resolve correctly.

​
Handling JSON stdout

​
Success output

Successful commands write parseable JSON to stdout. The output shape is application-defined and documented in APP.md. For example, the Agentic To-Do list command returns: 
{
  "ok": true,
  "command": "list",
  "count": 1,
  "items": [
    {
      "id": "td_0001",
      "title": "Write docs",
      "description": "",
      "status": "open",
      "dueAt": "2026-04-05",
      "createdAt": "2026-04-01T00:00:00.000Z",
      "updatedAt": "2026-04-01T00:00:00.000Z",
      "completedAt": null
    }
  ]
}
Parse the JSON from stdout. Do not rely on stderr or process output formatting for the primary result.

​
Failure output

Failing commands return a non-zero exit code and, when possible, a structured JSON error on stdout. For example: 
{
  "ok": false,
  "error": {
    "code": "CONFIRMATION_REQUIRED",
    "message": "remove requires --confirm."
  }
}
Treat any non-zero exit code as a failure, even if stdout is empty or unparseable.

​
Non-zero exit codes

When a command exits with a non-zero code:
  • Treat the invocation as failed.
  • Attempt to parse stdout as a structured JSON error.
  • If stdout is not valid JSON, fall back to any message available.
  • Do not silently swallow the failure or retry without user awareness.

​
stderr as diagnostics

The application may write diagnostics to stderr. Treat stderr as supplemental information — useful for debugging, but not part of the primary command contract. Do not parse stderr as structured output.

​
Stable identifiers and caching

The CLI should use stable command names and stable entity identifiers across invocations. When you cache results or script around command output, rely on entity IDs returned by the application (for example, td_0001) rather than on positions in a list or inferred names. Prefer re-reading current application state before risky mutations rather than trusting cached summaries.

​
Confirmation-required commands

Some commands are destructive. APP.md declares these in confirmationRequired: 
confirmationRequired:
  - remove
Before invoking any command listed in confirmationRequired, require an explicit user confirmation step. Do not invoke a destructive command on behalf of the agent without the user’s approval. The JSON error code CONFIRMATION_REQUIRED indicates the application itself enforces this — but your runtime should intercept the command before it reaches the CLI.
To detect confirmation-required commands, read confirmationRequired from the APP.md frontmatter at catalog time. Surface this information in your UI or agent context so the confirmation requirement is visible before the command runs.

​
Scheduling commands

If APP.md declares scheduling: supported, the application exposes scheduling-related CLI commands documented in the APP.md body. Read the APP.md body to learn what those commands are before attempting to invoke them. Do not invent a schedule command. Only invoke scheduling commands that APP.md explicitly documents. 
scheduling: supported
If scheduling is notSupported or absent, do not attempt any scheduling invocations.

​
Error handling

When surfacing errors from CLI execution:
  • Show structured error messages to the user when available (error.message from the JSON failure output).
  • Show error codes (error.code) to agents so they can respond appropriately — for example, by requesting user confirmation when the code is CONFIRMATION_REQUIRED.
  • Use stderr content as supplemental context for debugging, not as user-facing output.
  • Do not expose raw stack traces or internal application paths to users unless they are explicitly debugging.