# kusty command reference > Every kusty command, global flag, environment variable, error code and exit code, plus the resource commands generated from the Kustomer API. Source: https://developer.kustomer.com/docs/ai/kusty-reference This page is the complete surface of the public kusty build. kusty can describe itself too: `kusty schema dump` prints every command, flag and example as JSON, and `kusty --help --json` prints one command's manifest. ## Commands | Command | What it does | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `kusty api METHOD PATH` | Sends any request to any API path. [Flags](#api-flags). | | `kusty ` | Calls one API operation. See [resource commands](#resource-commands). | | `kusty config` | Interactive setup for profiles, API keys and OAuth (for people, not scripts) | | `kusty profile add NAME` | Adds a profile: `--org-subdomain`, `--tenant-url` or `--base-url`; `--api-key-env`; `--default` | | `kusty profile list` | Lists profiles | | `kusty profile use NAME` | Sets the default profile in the config file | | `kusty profile show [NAME]` | Shows a profile's settings | | `kusty context show` | The profile, org, base URL and credential source that would be used, without calling the API. `--fresh` also calls `/v1/users/current`. | | `kusty auth whoami` | Calls `/v1/users/current` to prove the credential works | | `kusty auth login` | Signs in with OAuth in your browser and stores the session | | `kusty auth status` | Shows session expiry, refresh-token state and scope | | `kusty auth refresh` | Renews the access token now | | `kusty auth logout` | Deletes the stored session | | `kusty app register` | Admin: registers and installs the private Kusty CLI app for OAuth. Needs `org.admin.apps`. | | `kusty app secret` | Admin: mints the OAuth client secret and stores it on the profile | | `kusty app status` | Checks whether the Kusty CLI app is installed | | `kusty mcp serve` | Runs the MCP server over stdio. Clients start it for you. | | `kusty mcp install` | Registers the MCP server and `/kusty` skill with AI clients: `--client`, `--all`, `--skill`, `--yes` | | `kusty mcp status` | Shows which clients have the server and skill | | `kusty mcp uninstall` | Removes them: `--client` or `--all`, `--skill` | | `kusty schema dump` | Every command, flag and example as JSON | | `kusty schema describe ` | One command's manifest, including its request body schema | | `kusty whats-new [topic]` | kusty release notes, newest first: `--product`, `--since YYYY-MM-DD`, `--limit` | | `kusty completions ` | Completion script for `zsh`, `bash`, `fish` or `powershell` | | `kusty version` | Version and build information | ## Global flags These work on every command. | Flag | Environment variable | Meaning | | ----------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------ | | `--output FORMAT` | | `jsonl` (default), `json`, `yaml` or `table` | | `--fields a,b.c` | | Keep only these dot-paths from `data` | | `--compact` | | Put `json` or `table` output on one line | | `--quiet` | | Drop the `warnings` array | | `--summary` | | With `--all`, write the stream summary to stdout instead of stderr | | `--profile NAME` | `KUSTY_PROFILE` | Profile to use | | `--api-key KEY` | `KUSTY_API_KEY`, or the profile's `api_key_env` | API key to use | | `--base-url URL` | `KUSTY_BASE_URL` | API base URL | | `--config PATH` | `KUSTY_CONFIG` | Config file. Default `~/.config/kusty/config.toml`. | | `--log-level LEVEL` | | `debug`, `info` (default), `warn` or `error` | | `--log-file PATH` | `KUSTY_LOG_FILE` | JSON-lines log. Default `$XDG_STATE_HOME/kusty/kusty.log`. | | `--dry-run` | | Print the resolved request instead of sending it | | `--read-only` | `KUSTY_READ_ONLY` | Reject writes | | `--idempotency-key KEY` | | Send an `Idempotency-Key` header on POSTs, which also makes them safe to retry | | `--confirm` | | Confirm a destructive operation. Needs `--yes` too. | | `--yes` | | Skip confirmation prompts | | `--validate` | | Check request bodies against JSON Schemas before sending. Default `true`. | | `--help --json` | | Print the command's manifest as JSON instead of running it | ## api flags | Flag | Meaning | | ------------------------ | ----------------------------------------------------------------- | | `--data JSON` | Request body inline, `@file.json` from a file, or `@-` from stdin | | `--field path=value` | Set one body field as a string. Repeatable. | | `--field path:=json` | Set one body field as raw JSON: number, boolean, array or object | | `--query k=v` | Add a query parameter. Repeatable. | | `--header 'Name: value'` | Add a header. Repeatable. | | `--all` | Follow `links.next` and stream every page as JSON lines | | `--limit N` | Sets `pageSize` | | `--cursor C` | Sets `page`, or passes an opaque cursor | Resource commands accept `--data`, `--field` and `--query` too. ### Field paths `--fields` (what to keep) and `--field` (what to send) share one syntax: | Path | Means | | ----------------- | --------------------------------- | | `attributes.name` | Nested key | | `emails.0.email` | Array item by index | | `tags.-1` | Append to an array (when writing) | | `price\.usd` | A key containing a literal dot | Missing objects and arrays are created when writing. Wildcards and queries (`*`, `?`, `#`, `@`, `|`) aren't supported. ## Envelopes ```json title="Success" { "schema_version": "1", "data": {}, "meta": { "request_id": "…", "duration_ms": 0, "next_cursor": "…" }, "warnings": [] } ``` ```json title="Error" { "schema_version": "1", "error": { "code": "NOT_FOUND", "message": "…", "hint": "…", "retryable": false } } ``` A successful response that isn't JSON (text or CSV) is returned as a string in `data` with a `NON_JSON_BODY` warning. ## Exit codes | Code | Meaning | Error codes | | ---- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | 0 | Success | | | 1 | Runtime error | `API_ERROR`, `INTERNAL`, `OUTPUT_FILTER_FAILED` | | 2 | Usage | `USAGE`, `INVALID_ARGUMENT`, `SCHEMA_VALIDATION_FAILED`, `PROMPT_REQUIRED`, `DESTRUCTIVE_CONFIRMATION_REQUIRED`, `READ_ONLY`, `CONFIG_INCOMPLETE` | | 3 | Authentication | `AUTH_REQUIRED`, `AUTH_EXPIRED`, `FORBIDDEN` | | 4 | Not found | `NOT_FOUND` | | 5 | Conflict | `CONFLICT`, `PRECONDITION_FAILED` | | 6 | Rate limited | `RATE_LIMITED` | | 7 | Server error | `SERVER_ERROR` | | 8 | Network | `NETWORK` (DNS, TLS, connection) | ```bash title="Branch on the exit code" kusty api GET "/v1/customers/email=$EMAIL" --fields id > customer.json case $? in 0) jq -r .data.id customer.json ;; 4) echo "no customer with that email" ;; 3) echo "run: kusty auth login" >&2; exit 1 ;; *) jq -r .error.hint customer.json >&2; exit 1 ;; esac ``` ## Error codes | Code | When | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------- | | `USAGE` | Unknown command, wrong arguments, missing required flag, bad `--output` | | `INVALID_ARGUMENT` | A flag or argument has an invalid value | | `CONFIG_INCOMPLETE` | No profile resolved. Run `kusty config` or `kusty profile add`. | | `PROMPT_REQUIRED` | The command needs input kusty won't prompt for. Pass it as a flag. | | `SCHEMA_VALIDATION_FAILED` | The request body doesn't match the API's schema | | `DESTRUCTIVE_CONFIRMATION_REQUIRED` | A delete without both `--confirm` and `--yes` | | `READ_ONLY` | A write while read-only mode is on | | `AUTH_REQUIRED` | No credential, or the session can't be refreshed | | `AUTH_EXPIRED` | The credential expired | | `FORBIDDEN` | The credential lacks the role or the org lacks the feature | | `NOT_FOUND` | The resource or path doesn't exist | | `CONFLICT`, `PRECONDITION_FAILED` | The API refused because of the resource's state | | `RATE_LIMITED` | Still rate limited after retries. See [Rate limits](https://developer.kustomer.com/docs/concepts/rate-limits). | | `SERVER_ERROR` | Kustomer returned a 5xx | | `NETWORK` | DNS, TLS or connection failure | | `API_ERROR` | Any other API error | | `INTERNAL` | A bug in kusty | | `OUTPUT_FILTER_FAILED` | An output filter couldn't process the response, so it was withheld | New codes may be added; existing codes never change meaning. ## Resource commands Resource commands are generated from the [public API reference](https://developer.kustomer.com/api): one subcommand per operation, with path and query parameters as flags. Parameter names keep their spelling (`--pageSize`, `--evaluationId`), brackets are dropped and dots become dashes (`page.size` becomes `--page-size`). A parameter that collides with a global flag gets a `q-` prefix: the `fields` query parameter is `--q-fields`, because `--fields` always means output projection. ```bash kusty customers --help # list subcommands kusty customers get-by-email --help --json # exact flags and body schema kusty customers get-by-email --email sam@example.com kusty evaluations runevaluation --evaluationId 6716c1d2c4e5f60012ab36ea --data '{"runsPerTestCase":3}' ``` | Area | Resources | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Core | `customers`, `customers-bulk`, `customers-conversations`, `customers-drafts`, `customers-events`, `customers-kobjects`, `customers-merges`, `customers-messages`, `customers-notes`, `customers-unmasking-windows`, `conversations`, `conversations-bulk`, `conversations-forwards`, `conversations-messages`, `conversations-notes`, `conversations-tags`, `conversations-time`, `messages`, `messages-bulk`, `klasses`, `kobjects-custom-objects`, `kobjects-custom-objects-bulk` | | AI | `summaries`, `automations`, `evaluations`, `evaluation-test-cases`, `evaluation-runs`, `evaluation-test-case-results` | | Automation | `workflows`, `workflow-variables`, `workflow-processes-errors` | | Identity | `users`, `users-by-id`, `teams`, `teams-by-id`, `role-groups`, `auth-settings`, `auth-tokens` | | Knowledge base | `knowledge-bases`, `knowledge-bases-custom-domains`, `articles`, `articles-public`, `articles-schedules`, `articles-versioning-and-languages`, `categories`, `categories-public`, `tags-knowledge-base`, `themes`, `themes-drafts-and-revisions`, `themes-theme-files` | | Routing and work | `queues`, `queue-rules`, `routes`, `routing-user-statuses`, `team-routing-settings`, `work-items`, `work-sessions`, `work-sessions-current`, `work-sessions-by-session-id`, `business-schedules`, `slas` | | Apps and integrations | `apps`, `hooks-web-hooks`, `hooks-form-hooks`, `hooks-email-hooks`, `outbound-web-hooks`, `outbound-web-hooks-transactions`, `kviews-klass-views`, `cards`, `tracking-events` | | Everything else | `attachments`, `audit-logs`, `brands`, `bulk-operations`, `chat-settings`, `companies`, `companies-bulk`, `custom-attributes`, `drafts`, `drafts-attachments`, `forms`, `forwards-attachments`, `media`, `metrics`, `notes`, `notes-bulk`, `notes-conversations`, `notifications`, `notifications-logs`, `notifications-settings`, `satisfaction`, `search`, `search-filters`, `search-filters-folders`, `search-filters-pinned`, `settings`, `settings-specific-user`, `shortcuts`, `shortcuts-categories`, `snippets`, `snoozes`, `spam`, `sub-statuses`, `templates` | Destructive operations need `--confirm --yes`, the same as `kusty api DELETE`.