Generated CLI

A CLI Target turns your API operations into commands for terminals, scripts, CI, and coding agents. There is one cli Target. Its package includes the client it needs; you do not need to create or release an SDK Target.

Distribute the executable for your customer's operating system. Running it requires no language runtime. The generated README and publishing guide explain how to build the source package and package releases.

The examples below use a fictional Parcel API and its parcel command. Use the command name in your generated README. For a runnable public example, see Try a sample CLI.

Commands and flags

parcel shipments list --limit 50
parcel shipments get shp_123
parcel shipments create --recipient "Ada Lovelace" --service ground

Path parameters are positional arguments in path order. Query, header, and body parameters become flags. Use parcel <resource> <command> --help for the names, types, and required inputs for your Spec.

Command names come from operation IDs and paths. Shared naming rules remove redundant resource words and recognizable controller prefixes. See SDK naming rules.

Flags from the spec

• Boolean flags accept true or false; numeric and enum flags are checked locally.
• Array fields accept repeated flags, comma-separated values, or a JSON array: --tags a --tags b, --tags a,b, or --tags '["a","b"]'.
• Object fields accept JSON: --metadata '{"team":"core"}'.
• --data '<json>' supplies a body. Field flags override matching fields in that body. Use --data @body.json to read a file or --data - to read stdin.
• Nullable fields accept null. Omitted optional fields stay absent. Use a JSON body to distinguish the string "null" from JSON null.
• Names that collide with global CLI flags receive a location prefix, such as --body-data.

parcel shipments create \
  --data '{"recipient":"Ada Lovelace","service":"ground"}' \
  --service express

Output and exit codes

API commands print JSON on stdout. Errors use stderr. Use the process exit code to decide whether a command succeeded:

With --mode agent or --format json, failures use an envelope with status, issues, and next_steps. issues[].code identifies the failure. When the API rejects a request, the message carries the API's own explanation, next_steps starts with the recovery steps the API suggested, retryable says whether the same command can succeed unchanged, and detail holds the status, request ID, and error body. A failure the CLI cannot classify uses CALL_FAILED. Malformed input, such as invalid JSON in a flag, exits 2 before any request is sent. Do not infer an HTTP status from the process exit code.

--fields id,status projects matching paths from the result. JSON remains the output format.

Streaming every page

A paginated command prints its first page. Use the cursor or pagination fields declared by your API to request another page. --all follows pages and writes one JSON item per line:

parcel shipments list --all > shipments.ndjson
parcel shipments list --all | jq -r '.id'

Help

parcel --help
parcel shipments --help
parcel shipments create --help
parcel help --json
parcel docs shipments create --json

help --json lists resource names. Operation help and docs describe an individual command. The package also includes api.md and api.json for human and machine-readable operation reference.

Auth and configuration

Credential flags override environment variables and saved credentials. The generated help lists the variables for your API. For a Parcel API using bearer authentication:

export PARCEL_TOKEN="your-api-token"
parcel shipments list

Supported credential inputs include --token, --api-key, and --username with --password, according to the Spec's authentication schemes. --base-url overrides the API destination; --header "Name: value" adds a request header.

Login, logout, whoami

Run parcel login --help for the login methods configured for your API. Supply a credential directly or use a configured browser, device, or approval flow:

parcel login --token "$PARCEL_TOKEN"
parcel whoami
parcel logout

The CLI stores a saved session in a credentials file accessible only to the current user. It honors XDG_CONFIG_HOME. whoami calls the configured identity operation; its availability depends on the Spec and authentication settings. See Authentication.

--no-browser prints the approval URL for a configured login flow. --non-interactive requires credential input instead of an interactive login.

Config

parcel config list
parcel config path
parcel config set base-url https://api.parcel.example
parcel config get base-url
parcel config unset base-url

Supported keys are base-url, environment, and docs-url. An environment must be declared in the generated configuration. Environment variables and command flags can override saved settings.

Hosted MCP handoff

When your Target includes a hosted MCP URL, the CLI can configure a supported client:

parcel mcp --help
parcel mcp install --vscode

Review the selected client's settings and follow its authentication instructions. See Connect MCP clients.

Init

parcel init writes an AGENTS.md block describing the CLI in the current directory. Use parcel init --help to inspect additional setup options before changing a project.

Agent guide, auth check, and doctor

parcel agent-guide --format json
parcel auth check --format json
parcel doctor --format json

agent-guide describes commands and conventions. auth check reports resolved authentication without printing credentials. doctor checks local setup and endpoint connectivity. A reachable endpoint is not proof that a credential can call every operation; verify access with an appropriate read command.

Agent mode

Use --mode agent for structured diagnostics. Destructive operations require --force or --yes; inspect the operation before supplying confirmation.

--out <dir> saves file-shaped API responses into a directory. It applies to operations whose response describes files, such as Typeship's packages generate.

Non-interactive mode

Pass --non-interactive when a script must not prompt. Supply credentials through the environment or explicit credential input. Use exit codes and JSON output to handle failures.

Docs

parcel docs shipments create
parcel docs shipments create --json
parcel docs search "create a shipment"
parcel docs read https://docs.parcel.example/guides/create-a-shipment.md

Local operation documentation comes from the Spec. Guide search and reading use the documentation URLs configured for the Target. See Connect your guides.

Read your changelog

Set config.cli.changelog_url to a public Markdown, plain text, or static HTML URL and regenerate. The CLI then includes:

parcel changelog
parcel changelog --json

The command fetches release notes without API credentials. Clear the URL and regenerate to remove it.

Completion

Generate completions for Bash, Zsh, or Fish:

parcel completion bash > parcel-completion.bash

Load the resulting file using your shell's completion setup.

Upgrade

parcel upgrade --check reports the current and published versions without installing. Archive installations check GitHub releases for the platform's versioned archive and checksums.txt, not the Go module proxy. Replace an archive installation manually after verifying its checksum. Source builds report rebuild instructions.

On Unix, parcel upgrade can replace a writable Go-installed executable while preserving its installed filename. Windows and read-only installations require manual replacement. Publishing and update availability depend on the repository configured for the Target. The CLI does not send automatic update notices, including in non-interactive mode; only upgrade checks versions.

Feedback

When a feedback URL is configured, parcel feedback opens it or prints the URL in agent mode.

Debug output

--debug writes request diagnostics to stderr. Keep stdout separate when piping API results.

Runtime validation

--validate checks supported request and response schema constraints. Validation failures exit nonzero. Validation covers a subset of JSON Schema; business rules and unsupported constraints need application checks. See SDK runtime validation.

Uploads and event streams

Multipart operations accept local file paths for binary fields. Operations with a binary body use --file <path>. Streaming operations write events as JSON lines. Use the command's help for its generated flags.

For a binary response, redirect stdout or pass --output <file>; avoid writing binary data to a terminal.

Webhooks listen

When configured for the Target, parcel webhooks listen forwards webhook events to a local endpoint. This uses the Pro webhook relay service. parcel webhooks fake emits sample events from the Spec. See Webhooks for configuration and service requirements.

In CI

Install the executable appropriate to your runner, then supply credentials as a CI secret:

- name: Export shipment IDs
  env:
    PARCEL_TOKEN: ${{ secrets.PARCEL_TOKEN }}
  run: parcel shipments list --all | jq -r '.id' > shipment-ids.txt

Generated tests

The source package includes offline tests for generated commands. Set config.cli.unit_tests to true on the CLI Target to include helper tests too. Follow the generated README to run them. Tests need no API credentials.

Add a multi-step command

Use a wrapper around the executable to combine commands, polling, and human handoffs. See Add a custom command for a pattern that leaves generated command routing intact.

Try a sample CLI

With the Typeship CLI installed, generate the public sample:

typeship packages generate \
  --spec '{"url":"https://typeship.dev/examples/petstore/openapi.yaml"}' \
  --target '{"type":"cli"}' \
  --out ./petstore-cli
cd petstore-cli
go build -o petstore .
./petstore pets list --json --validate

Building the source requires the toolchain version listed in its generated README. Distribute the built executable to users; they do not need that toolchain.

The sample returns [{"id":"pet_1","name":"Mochi"}].

Change the command name

Set config.cli.command_name before generating, for example --config '{"cli":{"command_name":"petshop"}}'. Build the executable under the same name, then run ./petshop --help. Save this configuration on a Project or Target to retain it across regeneration.