kusty command reference

Every kusty command, global flag, environment variable, error code and exit code, plus the resource commands generated from the Kustomer API.

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 <command> --help --json prints one command's manifest.

Commands

CommandWhat it does
kusty api METHOD PATHSends any request to any API path. Flags.
kusty <resource> <subcommand>Calls one API operation. See resource commands.
kusty configInteractive setup for profiles, API keys and OAuth (for people, not scripts)
kusty profile add NAMEAdds a profile: --org-subdomain, --tenant-url or --base-url; --api-key-env; --default
kusty profile listLists profiles
kusty profile use NAMESets the default profile in the config file
kusty profile show [NAME]Shows a profile's settings
kusty context showThe profile, org, base URL and credential source that would be used, without calling the API. --fresh also calls /v1/users/current.
kusty auth whoamiCalls /v1/users/current to prove the credential works
kusty auth loginSigns in with OAuth in your browser and stores the session
kusty auth statusShows session expiry, refresh-token state and scope
kusty auth refreshRenews the access token now
kusty auth logoutDeletes the stored session
kusty app registerAdmin: registers and installs the private Kusty CLI app for OAuth. Needs org.admin.apps.
kusty app secretAdmin: mints the OAuth client secret and stores it on the profile
kusty app statusChecks whether the Kusty CLI app is installed
kusty mcp serveRuns the MCP server over stdio. Clients start it for you.
kusty mcp installRegisters the MCP server and /kusty skill with AI clients: --client, --all, --skill, --yes
kusty mcp statusShows which clients have the server and skill
kusty mcp uninstallRemoves them: --client or --all, --skill
kusty schema dumpEvery command, flag and example as JSON
kusty schema describe <command…>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 <shell>Completion script for zsh, bash, fish or powershell
kusty versionVersion and build information

Global flags

These work on every command.

FlagEnvironment variableMeaning
--output FORMATjsonl (default), json, yaml or table
--fields a,b.cKeep only these dot-paths from data
--compactPut json or table output on one line
--quietDrop the warnings array
--summaryWith --all, write the stream summary to stdout instead of stderr
--profile NAMEKUSTY_PROFILEProfile to use
--api-key KEYKUSTY_API_KEY, or the profile's api_key_envAPI key to use
--base-url URLKUSTY_BASE_URLAPI base URL
--config PATHKUSTY_CONFIGConfig file. Default ~/.config/kusty/config.toml.
--log-level LEVELdebug, info (default), warn or error
--log-file PATHKUSTY_LOG_FILEJSON-lines log. Default $XDG_STATE_HOME/kusty/kusty.log.
--dry-runPrint the resolved request instead of sending it
--read-onlyKUSTY_READ_ONLYReject writes
--idempotency-key KEYSend an Idempotency-Key header on POSTs, which also makes them safe to retry
--confirmConfirm a destructive operation. Needs --yes too.
--yesSkip confirmation prompts
--validateCheck request bodies against JSON Schemas before sending. Default true.
--help --jsonPrint the command's manifest as JSON instead of running it

api flags

FlagMeaning
--data JSONRequest body inline, @file.json from a file, or @- from stdin
--field path=valueSet one body field as a string. Repeatable.
--field path:=jsonSet one body field as raw JSON: number, boolean, array or object
--query k=vAdd a query parameter. Repeatable.
--header 'Name: value'Add a header. Repeatable.
--allFollow links.next and stream every page as JSON lines
--limit NSets pageSize
--cursor CSets 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:

PathMeans
attributes.nameNested key
emails.0.emailArray item by index
tags.-1Append to an array (when writing)
price\.usdA key containing a literal dot

Missing objects and arrays are created when writing. Wildcards and queries (*, ?, #, @, |) aren't supported.

Envelopes

Success
{ "schema_version": "1", "data": {}, "meta": { "request_id": "…", "duration_ms": 0, "next_cursor": "…" }, "warnings": [] }
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

CodeMeaningError codes
0Success
1Runtime errorAPI_ERROR, INTERNAL, OUTPUT_FILTER_FAILED
2UsageUSAGE, INVALID_ARGUMENT, SCHEMA_VALIDATION_FAILED, PROMPT_REQUIRED, DESTRUCTIVE_CONFIRMATION_REQUIRED, READ_ONLY, CONFIG_INCOMPLETE
3AuthenticationAUTH_REQUIRED, AUTH_EXPIRED, FORBIDDEN
4Not foundNOT_FOUND
5ConflictCONFLICT, PRECONDITION_FAILED
6Rate limitedRATE_LIMITED
7Server errorSERVER_ERROR
8NetworkNETWORK (DNS, TLS, connection)
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

CodeWhen
USAGEUnknown command, wrong arguments, missing required flag, bad --output
INVALID_ARGUMENTA flag or argument has an invalid value
CONFIG_INCOMPLETENo profile resolved. Run kusty config or kusty profile add.
PROMPT_REQUIREDThe command needs input kusty won't prompt for. Pass it as a flag.
SCHEMA_VALIDATION_FAILEDThe request body doesn't match the API's schema
DESTRUCTIVE_CONFIRMATION_REQUIREDA delete without both --confirm and --yes
READ_ONLYA write while read-only mode is on
AUTH_REQUIREDNo credential, or the session can't be refreshed
AUTH_EXPIREDThe credential expired
FORBIDDENThe credential lacks the role or the org lacks the feature
NOT_FOUNDThe resource or path doesn't exist
CONFLICT, PRECONDITION_FAILEDThe API refused because of the resource's state
RATE_LIMITEDStill rate limited after retries. See Rate limits.
SERVER_ERRORKustomer returned a 5xx
NETWORKDNS, TLS or connection failure
API_ERRORAny other API error
INTERNALA bug in kusty
OUTPUT_FILTER_FAILEDAn 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: 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.

Shell
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}'
AreaResources
Corecustomers, 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
AIsummaries, automations, evaluations, evaluation-test-cases, evaluation-runs, evaluation-test-case-results
Automationworkflows, workflow-variables, workflow-processes-errors
Identityusers, users-by-id, teams, teams-by-id, role-groups, auth-settings, auth-tokens
Knowledge baseknowledge-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 workqueues, 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 integrationsapps, hooks-web-hooks, hooks-form-hooks, hooks-email-hooks, outbound-web-hooks, outbound-web-hooks-transactions, kviews-klass-views, cards, tracking-events
Everything elseattachments, 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.