> ## Documentation Index > Fetch the complete documentation index at: https://docs.usecustory.com/llms.txt > Use this file to discover all available pages before exploring further. # Command reference > Searchable reference for public Custory CLI commands. Use this page when you need the exact command shape. For workflow guidance, start with [CLI quickstart](/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 ` | 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. ## `custory login` Synopsis: ```bash theme={null} 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: ```bash theme={null} custory login custory login --no-browser ``` Related: `custory status`, `custory logout` ## `custory logout` Synopsis: ```bash theme={null} custory logout [--json] ``` Signs out on this device, removes the local credential, and revokes the remote CLI session when possible. Examples: ```bash theme={null} custory logout custory logout --json ``` Related: `custory login` ## `custory status` Synopsis: ```bash theme={null} custory status [--json] ``` Shows the signed-in user, accessible workspace count, credential store type, and latest setup status when one exists. Examples: ```bash theme={null} custory status custory status --json ``` Related: `custory login`, `custory workspace list`, `custory doctor` ## `custory workspace list` Synopsis: ```bash theme={null} custory workspace list [--json] ``` Lists the workspaces the signed-in account can access. Human-readable output includes workspace name, slug, and role. Examples: ```bash theme={null} custory workspace list custory workspace list --json ``` Related: `custory init`, `custory mcp install` ## `custory init` Synopsis: ```bash theme={null} custory init [--workspace ] [--website |--brief |--stdin] [--journey ] [--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: ```bash theme={null} custory init --resume ``` Examples: ```bash theme={null} 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. ### `custory login --json` ```json theme={null} { "status": "authenticated", "user": { "email": "founder@example.com", "firstName": "Avery", "lastName": "Stone" }, "credentialStore": "macOS Keychain" } ``` ### `custory logout --json` ```json theme={null} { "status": "logged_out" } ``` ### `custory status --json` ```json theme={null} { "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` ```json theme={null} { "workspaces": [ { "_id": "workspace_example", "name": "Acme", "slug": "acme", "ownerId": "user_example", "isOwner": true, "role": "OWNER" } ] } ``` ### `custory init --json` ```json theme={null} { "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` ```json theme={null} { "tools": [ { "name": "custory.list_personas", "description": "List personas available in the workspace." } ] } ``` ### `custory tools describe --json` ```json theme={null} { "tool": { "name": "custory.list_personas", "description": "List personas available in the workspace.", "inputSchema": { "type": "object", "properties": {} } } } ``` ### `custory tools call --json` ```json theme={null} { "result": { "success": true, "personas": [] } } ``` ### `custory agent run --json` ```json theme={null} { "result": { "success": true, "message": "Delegated run complete.", "toolCalls": [] } } ``` ### `custory mcp install --json` ```json theme={null} { "status": "installed", "client": "codex", "workspace": "acme", "expiresAt": 1760000000000, "verification": { "server": "custory-mcp", "toolCount": 12, "workspaceBound": true } } ``` ### `custory mcp verify --json` ```json theme={null} { "status": "verified", "client": "codex", "workspace": "acme", "expiresAt": 1760000000000, "verification": { "server": "custory-mcp", "toolCount": 12, "workspaceBound": true } } ``` ### `custory mcp uninstall --json` ```json theme={null} { "status": "uninstalled", "client": "codex", "credentialRevoked": true } ``` ### `custory doctor --json` ```json theme={null} { "schemaVersion": 1, "status": "healthy", "checks": [ { "code": "RUNTIME_SUPPORTED", "status": "pass", "message": "Node.js runtime is supported." } ] } ``` ### Error envelope ```json theme={null} { "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: ```bash theme={null} custory tools list [--json] ``` Lists Custory tools available to the signed-in account. Examples: ```bash theme={null} custory tools list custory tools list --json ``` Related: `custory tools describe`, `custory tools call` ## `custory tools describe ` Synopsis: ```bash theme={null} custory tools describe [--json] ``` Prints the schema and metadata for one Custory tool. Examples: ```bash theme={null} custory tools describe custory.list_personas custory tools describe custory.get_journey_state --json ``` Related: `custory tools list`, `custory tools call` ## `custory tools call ` Synopsis: ```bash theme={null} custory tools call [--input |--file |--stdin] [--json] ``` Calls one Custory tool with a JSON object as input. If no input source is provided, the CLI sends `{}`. Examples: ```bash theme={null} 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: ```bash theme={null} custory agent run --goal (--workspace |--journey ) [--mode journey|personas] [--model ] [--json] ``` Runs a bounded Custory agent task in a workspace or journey scope. The goal can also come from `--file` or `--stdin`. Examples: ```bash theme={null} 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: ```bash theme={null} custory mcp install [--client codex|claude|cursor] [--workspace ] [--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: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} custory mcp verify --client codex custory mcp verify --client claude --json ``` Related: `custory doctor` ## `custory mcp uninstall` Synopsis: ```bash theme={null} 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: ```bash theme={null} custory mcp uninstall --client codex custory mcp uninstall --client cursor --json ``` Related: `custory mcp install` ## `custory doctor` Synopsis: ```bash theme={null} 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: ```bash theme={null} 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](/cli/troubleshooting) if a command fails or returns an unclear error.