Command reference

Use this page when you need the exact command shape. For workflow guidance, start with CLI quickstart.

Global options

These options are shown in top-level help. Some are command-specific, so use them only with the commands listed here.

Option	Applies to	What it does
`--app-url <url>`	All commands that contact Custory	Override the Custory app used for discovery. Most users should not need this.
`--json`	Commands that return output	Write one machine-readable JSON document to stdout. Diagnostics go to stderr.
`--no-browser`	`login`, `init`	Print the authorization or journey URL instead of opening a browser.
`--force`	`login`	Start a new login even when a valid session exists.
`--refresh`	`doctor`	Allow doctor to safely refresh an expired session.
`-h`, `--help`	All commands	Show help.
`-v`, `--version`	Top level	Show the CLI version.

Parser constraints

The CLI rejects conflicting input before contacting Custory.

Command	Constraint
`custory init`	Use only one of `--website`, `--custom`, `--brief`, or `--stdin`.
`custory init --resume`	Do not combine `--resume` with a new source.
`custory tools call`	Use only one of `--input`, `--file`, or `--stdin`.
`custory agent run`	Use only one of `--goal`, `--file`, or `--stdin` for the goal.
`custory agent run --mode`	Value must be `journey` or `personas`.
`custory mcp --client`	Value must be `codex`, `claude`, or `cursor`.

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

Text input must be valid UTF-8. Tool-call input must parse to a JSON object. Synopsis:

custory login [--no-browser] [--force] [--json]

Signs in with browser-based authentication and stores the local CLI session. Use --force to start a new login even when a valid session exists. Use --no-browser when the terminal cannot open a browser. Examples:

custory login
custory login --no-browser

Related: custory status, custory logout

`custory logout`

Synopsis:

custory logout [--json]

Signs out on this device, removes the local credential, and revokes the remote CLI session when possible. Examples:

custory logout
custory logout --json

Related: custory login

`custory status`

Synopsis:

custory status [--json]

Shows the signed-in user, accessible workspace count, credential store type, and latest setup status when one exists. Examples:

custory status
custory status --json

Related: custory login, custory workspace list, custory doctor

`custory workspace list`

Synopsis:

custory workspace list [--json]

Lists the workspaces the signed-in account can access. Human-readable output includes workspace name, slug, and role. Examples:

custory workspace list
custory workspace list --json

Related: custory init, custory mcp install

`custory init`

Synopsis:

custory init [--workspace <name>] [--website <url>|--brief <file>|--stdin] [--journey <recommended|title>] [--yes] [--json]

Creates and verifies a first customer journey. Interactive mode asks for the missing decisions. Non-interactive mode requires --workspace, --journey, and one source: --website, --brief, or --stdin. --custom is an interactive source mode. In non-interactive runs, use --brief or --stdin for private text context. Use --resume to resume the latest unfinished setup:

custory init --resume

Examples:

custory init
custory init --workspace "Acme" --website https://acme.com --journey recommended --yes
custory init --workspace "Acme" --brief ./product-context.md --journey "New user activation" --yes --json

Related: custory status, custory doctor

JSON examples

These examples use fictional IDs and redacted values. JSON contracts can add fields over time, so automation should ignore unknown fields and branch on stable top-level fields.

{
  "status": "authenticated",
  "user": {
    "email": "founder@example.com",
    "firstName": "Avery",
    "lastName": "Stone"
  },
  "credentialStore": "macOS Keychain"
}

`custory logout --json`

{
  "status": "logged_out"
}

`custory status --json`

{
  "status": "authenticated",
  "user": {
    "email": "founder@example.com"
  },
  "workspaceCount": 1,
  "credentialStore": "Linux Secret Service",
  "onboarding": {
    "sessionId": "session_example",
    "status": "complete",
    "phase": "complete",
    "updatedAt": 1760000000000
  }
}

`custory workspace list --json`

{
  "workspaces": [
    {
      "_id": "workspace_example",
      "name": "Acme",
      "slug": "acme",
      "ownerId": "user_example",
      "isOwner": true,
      "role": "OWNER"
    }
  ]
}

`custory init --json`

{
  "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
}

`custory tools list --json`

{
  "tools": [
    {
      "name": "custory.list_personas",
      "description": "List personas available in the workspace."
    }
  ]
}

`custory tools describe --json`

{
  "tool": {
    "name": "custory.list_personas",
    "description": "List personas available in the workspace.",
    "inputSchema": {
      "type": "object",
      "properties": {}
    }
  }
}

`custory tools call --json`

{
  "result": {
    "success": true,
    "personas": []
  }
}

`custory agent run --json`

{
  "result": {
    "success": true,
    "message": "Delegated run complete.",
    "toolCalls": []
  }
}

`custory mcp install --json`

{
  "status": "installed",
  "client": "codex",
  "workspace": "acme",
  "expiresAt": 1760000000000,
  "verification": {
    "server": "custory-mcp",
    "toolCount": 12,
    "workspaceBound": true
  }
}

`custory mcp verify --json`

{
  "status": "verified",
  "client": "codex",
  "workspace": "acme",
  "expiresAt": 1760000000000,
  "verification": {
    "server": "custory-mcp",
    "toolCount": 12,
    "workspaceBound": true
  }
}

`custory mcp uninstall --json`

{
  "status": "uninstalled",
  "client": "codex",
  "credentialRevoked": true
}

`custory doctor --json`

{
  "schemaVersion": 1,
  "status": "healthy",
  "checks": [
    {
      "code": "RUNTIME_SUPPORTED",
      "status": "pass",
      "message": "Node.js runtime is supported."
    }
  ]
}

Error envelope

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

If an error is tied to onboarding, the envelope can also include phase.

`custory tools list`

Synopsis:

custory tools list [--json]

Lists Custory tools available to the signed-in account. Examples:

custory tools list
custory tools list --json

Related: custory tools describe, custory tools call

`custory tools describe <name>`

Synopsis:

custory tools describe <name> [--json]

Prints the schema and metadata for one Custory tool. Examples:

custory tools describe custory.list_personas
custory tools describe custory.get_journey_state --json

Related: custory tools list, custory tools call

`custory tools call <name>`

Synopsis:

custory tools call <name> [--input <json>|--file <path>|--stdin] [--json]

Calls one Custory tool with a JSON object as input. If no input source is provided, the CLI sends {}. Examples:

custory tools call custory.list_personas --input '{}'
custory tools call custory.get_journey_state --file ./input.json --json

Related: custory tools describe

`custory agent run`

Synopsis:

custory agent run --goal <goal> (--workspace <name>|--journey <id>) [--mode journey|personas] [--model <model>] [--json]

Runs a bounded Custory agent task in a workspace or journey scope. The goal can also come from --file or --stdin. Examples:

custory agent run --workspace "Acme" --goal "Review onboarding friction." --mode journey
custory agent run --journey journey_example --goal "Improve persona assumptions." --mode personas --json

Related: custory tools list

`custory mcp install`

Synopsis:

custory mcp install [--client codex|claude|cursor] [--workspace <name>] [--json]

Installs Custory MCP configuration for a supported client and verifies the connection. If the CLI can detect exactly one supported client, --client can be omitted. If your account has multiple workspaces, provide --workspace. Examples:

custory mcp install --client codex --workspace "Acme"
custory mcp install --client cursor --workspace acme --json

Related: custory mcp verify, custory mcp uninstall

`custory mcp verify`

Synopsis:

custory mcp verify [--client codex|claude|cursor] [--json]

Verifies that the configured MCP client can initialize Custory, list tools, and use the workspace binding. Examples:

custory mcp verify --client codex
custory mcp verify --client claude --json

Related: custory doctor

`custory mcp uninstall`

Synopsis:

custory mcp uninstall [--client codex|claude|cursor] [--json]

Removes the Custory MCP entry from the client configuration and revokes the stored MCP credential when installation metadata is available. Examples:

custory mcp uninstall --client codex
custory mcp uninstall --client cursor --json

Related: custory mcp install

`custory doctor`

Synopsis:

custory doctor [--refresh] [--json]

Checks runtime support, Custory discovery, service reachability, local session health, workspace access, recent onboarding health, canonical URLs, and MCP binding. Use --refresh when the local session may have expired. Examples:

custory doctor
custory doctor --refresh --json

Related: custory status, custory mcp verify

Exit codes

Code	Meaning	Common examples
`0`	Success	Command completed.
`1`	Unexpected failure	`UNEXPECTED_ERROR`, non-retryable onboarding failure, invalid API response.
`2`	Invalid input or missing required input	`INVALID_ARGUMENT`, `INPUT_REQUIRED`, `INPUT_TOO_LARGE`, `INPUT_INVALID`, `INPUT_FILE_UNREADABLE`, `INPUT_FILE_INVALID`, `UNKNOWN_COMMAND`, `MCP_CLIENT_REQUIRED`, `MCP_CONFIG_INVALID`, `MCP_NOT_INSTALLED`, `WORKSPACE_REQUIRED`, `EDITOR_UNAVAILABLE`, `EDITOR_FAILED`.
`3`	Authentication category reserved by the CLI contract	Prefer the named `AUTH_*` error code for recovery.
`4`	Recoverable failure or failed tool outcome	Retryable onboarding failure, failed direct tool result, `MCP_WORKSPACE_BINDING_INVALID`, unhealthy `doctor` report.
`5`	Partial success	Journey exists, but warnings or unfinished enrichment need review.
`130`	Operation canceled	`AUTH_CANCELED`, `OPERATION_CANCELED`.

Error codes

Code	Cause	Safe next action	Retry?
`INVALID_ARGUMENT`	Unknown, duplicate, conflicting, or malformed option.	Fix the command.	No.
`INPUT_REQUIRED`	Required prompt, flag, source, workspace, confirmation, or goal is missing.	Provide the missing input or rerun interactively.	No, not without changes.
`INPUT_TOO_LARGE`	Input exceeds the command limit.	Shorten the brief or use the right input path.	No.
`INPUT_INVALID`	Input is not valid UTF-8 text.	Save as valid UTF-8 and rerun.	No.
`INPUT_FILE_UNREADABLE`	The file cannot be read.	Check path and permissions.	After fixing.
`INPUT_FILE_INVALID`	The path is not a regular file.	Pass a regular text or JSON file.	After fixing.
`AUTH_REQUIRED`	No local CLI session exists.	Run `custory login`.	After login.
`AUTH_CANCELED`	Browser auth was canceled.	Rerun when ready.	Yes.
`AUTH_PROVIDER_UNREACHABLE`	Auth provider could not be reached.	Check network/proxy access.	Yes.
`AUTH_START_FAILED`	Device authorization could not start or returned an incomplete response.	Retry; contact support if persistent.	Yes if retryable.
`AUTH_TOKEN_INVALID`	Auth response did not include a usable access token.	Run `custory login` again.	Yes.
`AUTH_DENIED`	Browser authorization was denied.	Start login again and approve access.	After approving.
`AUTH_EXPIRED`	Browser authorization expired before completion.	Rerun `custory login`.	Yes.
`AUTH_TOKEN_FAILED`	Browser authorization failed during token polling.	Read the message, then retry if safe.	If retryable.
`AUTH_SESSION_EXPIRED`	Existing session cannot be refreshed.	Run `custory login` or `custory doctor --refresh`.	After login.
`AUTH_REFRESH_FAILED`	Session refresh failed.	Run `custory login`.	After login.
`AUTH_SESSION_INVALID`	Custory rejected the local session.	Run `custory login`.	After login.
`AUTH_REVOCATION_FAILED`	Logout or cleanup could not revoke the remote session.	Retry logout; contact support if persistent.	If retryable.
`CREDENTIAL_STORE_INVALID`	Local stored credential is malformed.	Run `custory logout`, then `custory login`.	After cleanup.
`CUSTORY_API_ERROR`	Custory API returned an error.	Read the message and retry only if marked retryable.	If retryable.
`CUSTORY_API_UNREACHABLE`	CLI API could not be reached.	Check network/proxy access.	Yes.
`CLI_DISCOVERY_UNREACHABLE`	`/.well-known/custory-cli.json` could not be reached.	Check network or `--app-url`.	Yes.
`CLI_DISCOVERY_INVALID`	Discovery document is missing or invalid.	Retry later or contact support.	Not usually.
`ONBOARDING_SESSION_NOT_FOUND`	No unfinished setup exists for `--resume`.	Start `custory init` again.	No.
`ONBOARDING_SESSION_EXPIRED`	The saved setup session expired.	Start a new setup and check for an existing journey first.	No.
`MCP_CLIENT_REQUIRED`	Client detection was ambiguous or missing.	Pass `--client codex`, `--client claude`, or `--client cursor`.	After fixing.
`MCP_CONFIG_INVALID`	Existing Claude/Cursor MCP JSON is malformed or `mcpServers` is not an object.	Fix the config JSON.	After fixing.
`MCP_CONFIG_WRITE_FAILED`	CLI could not update MCP config.	Check file permissions and rerun.	Yes.
`MCP_NOT_INSTALLED`	The selected client has no Custory MCP config.	Run `custory mcp install --client codex`, `claude`, or `cursor`.	After install.
`MCP_STATE_INVALID`	Private MCP installation metadata is malformed.	Reinstall MCP for the client.	After cleanup.
`MCP_STATE_WRITE_FAILED`	CLI could not update private MCP installation metadata.	Check permissions under `~/.custory`.	Yes.
`MCP_UNREACHABLE`	MCP endpoint could not be reached.	Check network access.	Yes.
`MCP_VERIFICATION_FAILED`	MCP initialize, tool list, or verification response failed.	Reinstall and verify again.	If retryable.
`MCP_WORKSPACE_BINDING_INVALID`	MCP credential is not bound to an accessible workspace.	Reinstall with the right workspace.	After reinstall.
`WORKSPACE_REQUIRED`	MCP install needs a specific accessible workspace.	Pass a workspace name, slug, or ID with `--workspace`.	After fixing.
`UNKNOWN_COMMAND`	Command is not public or was typed incorrectly.	Run `custory --help`.	No.
`EDITOR_UNAVAILABLE`	No `VISUAL` or `EDITOR` is configured for interactive custom input.	Set `VISUAL` or `EDITOR`, or use `--brief`/`--stdin`.	After fixing.
`EDITOR_FAILED`	Editor exited without saving the brief.	Save the brief and rerun.	After fixing.

Safe support data: command name, CLI version, error code, retryable flag, onboarding phase when present, and redacted doctor output. Do not share tokens, authorization headers, private brief text, or customer data.

Doctor check codes

Code	Meaning	Action when it fails or warns
`RUNTIME_SUPPORTED` / `RUNTIME_UNSUPPORTED`	Node.js runtime check.	Install Node.js `22.12` or newer.
`DISCOVERY_OK` / `DISCOVERY_UNREACHABLE`	CLI discovery route is reachable.	Check network access and `--app-url`.
`SERVICE_REACHABLE` / `SERVICE_UNREACHABLE` / `SERVICE_NOT_READY`	Custory worker and service readiness.	Retry later or share the doctor report with support.
`CREDENTIAL_STORE_OK` / `CREDENTIAL_STORE_UNREADABLE`	Local credential store can be read.	Run `custory logout`, then `custory login`.
`AUTH_REQUIRED`	No local session exists.	Run `custory login`.
`SESSION_OK` / `SESSION_REFRESH_OK`	Session is valid.	No action.
`SESSION_EXPIRED` / `SESSION_INVALID`	Session is expired or invalid.	Run `custory doctor --refresh` or `custory login`.
`WORKSPACE_ACCESS_OK` / `WORKSPACE_ACCESS_EMPTY`	Workspace permissions loaded.	Create or join a workspace if empty.
`ONBOARDING_JOB_OK` / `ONBOARDING_JOB_ATTENTION` / `ONBOARDING_JOB_NONE`	Latest setup health.	Run `custory init --resume` if attention is required.
`CANONICAL_URLS_OK` / `CANONICAL_URLS_INVALID`	Returned resource links use the expected Custory origin.	Do not open invalid links; contact support.
`MCP_NOT_INSTALLED`	No unambiguous MCP installation exists.	Run `custory mcp install --client codex`, `claude`, or `cursor`.
`MCP_BINDING_OK` / `MCP_BINDING_INVALID`	MCP config, tools, and workspace binding validate.	Reinstall MCP for the target client/workspace.

Next step

Read Troubleshooting if a command fails or returns an unclear error.

Start here

Workflows

Reference

Global options

Parser constraints

Input limits

`custory logout`

`custory status`

`custory workspace list`

`custory init`

JSON examples

`custory logout --json`

`custory status --json`

`custory workspace list --json`

`custory init --json`

`custory tools list --json`

`custory tools describe --json`

`custory tools call --json`

`custory agent run --json`

`custory mcp install --json`

`custory mcp verify --json`

`custory mcp uninstall --json`

`custory doctor --json`

Error envelope

`custory tools list`

`custory tools describe <name>`

`custory tools call <name>`

`custory agent run`

`custory mcp install`

`custory mcp verify`

`custory mcp uninstall`

`custory doctor`

Exit codes

Error codes

Doctor check codes

Next step

​Global options

​Parser constraints

​Input limits

​custory login

​custory logout

​custory status

​custory workspace list

​custory init

​JSON examples

​custory login --json

​custory logout --json

​custory status --json

​custory workspace list --json

​custory init --json

​custory tools list --json

​custory tools describe --json

​custory tools call --json

​custory agent run --json

​custory mcp install --json

​custory mcp verify --json

​custory mcp uninstall --json

​custory doctor --json

​Error envelope

​custory tools list

​custory tools describe <name>

​custory tools call <name>

​custory agent run

​custory mcp install

​custory mcp verify

​custory mcp uninstall

​custory doctor

​Exit codes

​Error codes

​Doctor check codes

​Next step

Global options

Parser constraints

Input limits

`custory login`

`custory logout`

`custory status`

`custory workspace list`

`custory init`

JSON examples

`custory login --json`

`custory logout --json`

`custory status --json`

`custory workspace list --json`

`custory init --json`

`custory tools list --json`

`custory tools describe --json`

`custory tools call --json`

`custory agent run --json`

`custory mcp install --json`

`custory mcp verify --json`

`custory mcp uninstall --json`

`custory doctor --json`

Error envelope

`custory tools list`

`custory tools describe <name>`

`custory tools call <name>`

`custory agent run`

`custory mcp install`

`custory mcp verify`

`custory mcp uninstall`

`custory doctor`

Exit codes

Error codes

Doctor check codes

Next step