Automation and JSON

Use this page when the CLI needs to run predictably without interactive prompts.

What this is

The CLI supports non-interactive journey creation, machine-readable JSON output, bounded standard input, and stable exit-code categories. Use these modes for scripts, CI-like tasks, and coding-agent workflows.

Non-interactive `init`

Non-interactive custory init requires:

--workspace <name|slug|id>
--journey <recommended|title>
one source: --website <url>, --brief <file>, or --stdin

Example:

custory init \
  --workspace "Acme" \
  --website https://acme.com \
  --journey recommended \
  --yes \
  --json

Without the required flags, the CLI exits with invalid input.

JSON output

Use --json when another process will read the result:

custory init \
  --workspace "Acme" \
  --brief ./product-context.md \
  --journey "New user activation" \
  --yes \
  --json

With --json, the command writes one JSON document to stdout. Progress and diagnostics go to stderr. That separation lets scripts parse stdout without losing useful human diagnostics.

Stable top-level fields

Successful init --json output includes stable top-level fields like:

{
  "schemaVersion": 1,
  "status": "complete",
  "phase": "complete",
  "sessionId": "session_example",
  "workspace": {
    "id": "workspace_example",
    "name": "Acme",
    "slug": "acme",
    "url": "https://app.usecustory.com/acme"
  },
  "journey": {
    "id": "journey_example",
    "name": "New user activation",
    "slug": "new-user-activation",
    "url": "https://app.usecustory.com/acme/journey/new-user-activation",
    "stageCount": 5,
    "stepCount": 12,
    "itemCount": 10
  },
  "personaIds": ["persona_example"],
  "warnings": [],
  "verifiedAt": 1760000000000
}

The example uses fictional IDs. Do not build scripts that depend on exact counts or names unless your input controls them. Treat schemaVersion, status, sessionId, workspace, journey, personaIds, warnings, and verifiedAt as the stable top-level contract for successful init output. Custory may add fields over time. Automation should ignore unknown fields. Error output uses this envelope:

{
  "schemaVersion": 1,
  "status": "error",
  "error": {
    "code": "INPUT_REQUIRED",
    "message": "Noninteractive init requires --workspace and --journey.",
    "retryable": false
  }
}

Error messages are user-safe and token-redacted. Scripts should branch on error.code first, then use retryable to decide whether retrying is reasonable.

Standard input rules

Use --stdin for text input from another command:

printf '%s\n' "Product context..." | custory init \
  --workspace "Acme" \
  --stdin \
  --journey recommended \
  --yes \
  --json

For init, standard input is bounded UTF-8 text. Very large input is rejected with INPUT_TOO_LARGE. For direct tool calls, --stdin must contain a JSON object.

Input limits

Input path	Limit
`init --brief`	`100,000` bytes
`init --stdin`	`100,000` bytes
`agent run --file`	`100,000` bytes
`agent run --stdin`	`100,000` bytes
`tools call --input`	`8,192` bytes
`tools call --file`	`17 MiB`
`tools call --stdin`	`17 MiB`
Website response body	`1,500,000` bytes

All text input must be valid UTF-8.

Exit codes

Exit code	Meaning	Retry guidance
`0`	Success	No retry needed.
`1`	Unexpected failure	Check the error. Retry only after understanding the cause.
`2`	Invalid input or required input missing	Fix the command or input. Do not blind retry.
`3`	Authentication category reserved by the CLI contract	Prefer the `AUTH_*` error code for recovery. Run `custory login` or `custory doctor --refresh`.
`4`	Recoverable failure or failed tool outcome	Retry may be safe after checking the message.
`5`	Partial success	Open the returned journey and review warnings.
`130`	Canceled operation	Rerun when ready.

Safe retries

If a create run is interrupted, prefer:

custory init --resume --yes --json

If the session expired or no unfinished setup exists, start a new run and check Custory for an existing journey before creating another one.

Run a bounded Custory agent task

Use custory agent run when you want Custory’s agent to work inside a workspace or journey scope. Workspace-scoped example:

custory agent run \
  --workspace "Acme" \
  --goal "Review the activation journey and suggest missing onboarding touchpoints." \
  --mode journey \
  --json

Journey-scoped example:

custory agent run \
  --journey journey_example \
  --goal "Find unclear persona assumptions and suggest improvements." \
  --mode personas \
  --json

custory agent run requires a goal through --goal, --file, or --stdin, and requires either --workspace or --journey.

Next step

Read Command reference for the exact command contracts.

Start here

Workflows

Reference

What this is

Non-interactive `init`

JSON output

Stable top-level fields

Standard input rules

Input limits

Exit codes

Safe retries

Run a bounded Custory agent task

Next step

​What this is

​Non-interactive init

​JSON output

​Stable top-level fields

​Standard input rules

​Input limits

​Exit codes

​Safe retries

​Run a bounded Custory agent task

​Next step

What this is

Non-interactive `init`

JSON output

Stable top-level fields

Standard input rules

Input limits

Exit codes

Safe retries

Run a bounded Custory agent task

Next step