Typeship CLI

Use the typeship CLI to manage Projects, generate Targets, and inspect results from a terminal or pipeline. It calls Typeship’s public API. Your generated CLI calls your own API.

It provides spec-derived flags, JSON output, stable exit codes, authentication, configuration, documentation search, and shell completion. See CLI Targets for shared behavior. This page covers Typeship-specific commands.

Install

Download the executable for your operating system from the Typeship CLI releases, extract the archive, and place typeship (typeship.exe on Windows) on your PATH.

typeship --version

The executable needs no language runtime. It reads TYPESHIP_TOKEN and stores local state under ~/.config/typeship/, honoring XDG_CONFIG_HOME.

Log in

typeship login                             # opens the console; approve once, a key is minted for this machine
typeship login --no-browser                # prints the approval link instead (headless, or an agent relaying it to you)
typeship login --token ak_...        # a key you already have
echo "$TYPESHIP_TOKEN" | typeship login --with-token   # from a secret, in scripts
typeship whoami                            # GET /api/v1/organization

typeship login opens /cli-auth, where you approve the machine and choose an organization when needed. The Typeship CLI names the key after the machine so you can revoke it later under API keys. It saves the key in a credentials file readable only by the current user.

typeship logout revokes keys minted through this flow. It does not revoke a key you supplied yourself.

TYPESHIP_TOKEN and --token take precedence over stored credentials, so CI does not need a login step.

Generate a package

One-shot generation works without signing in. Use a Typeship API key when you need your organization’s plan limits:

typeship packages generate \
  --spec '{"url":"https://typeship.dev/examples/petstore/openapi.yaml"}' \
  --target '{"type":"cli"}' > result.json

--spec accepts a URL or inline Spec. A one-shot run takes one Target descriptor, such as --target '{"type":"cli"}'. Its type is cli, mcp, typescript_sdk, python_sdk, or go_sdk.

Run the command again for another package, or create a Project to keep several Targets current. --config '{...}' takes the same generated-client configuration as a Project.

The response contains files, coded warnings, and coverage, including any Free-plan omissions.

One-shot generation runs for at most 5 minutes on the server. The Typeship CLI waits 60 seconds per attempt by default; pass --timeout 300 (or set TYPESHIP_TIMEOUT) for large Specs. If an attempt fails, it retries with the same idempotency key and reports the original failure and its request_id, not the retry's idempotency_key_in_use.

Manage projects

typeship projects list --all
typeship projects create --name "Sample API" \
  --spec '{"source":{"type":"url","url":{"url":"https://typeship.dev/examples/petstore/openapi.yaml"}}}' \
  --targets '[{"name":"Sample CLI","type":"cli"},{"name":"Sample MCP","type":"mcp","deliveries":[{"type":"hosted_mcp"}]},{"name":"Sample TypeScript SDK","type":"typescript_sdk"}]'
typeship projects get prj_...
typeship specs update spec_... --patches '[{"op":"set","path":"/info/title","value":"Sample API"}]'
typeship targets list --project-id prj_...
typeship drafts update drf_... --version-next 0.7.0
typeship releases list --target-id tgt_...

New Projects start automatic generation by default. Review the first Generation and any destination pull request before merging. Pass --auto-generate false when creating a Project if you need manual generation.

To remove a Project, use typeship projects delete <project_id>. Inspect the Project first and review the command’s confirmation before deleting it.

Object-valued fields such as --targets, --deliveries, and --config take JSON. Put initial Deliveries inside each Target descriptor.

After creation, add a Delivery with typeship deliveries create --data '{"target_id":"tgt_...","type":"repository","repository":{...}}', and change or remove one with typeship deliveries update dlv_... or typeship deliveries delete dlv_.... Use --data '<json>' on any command when supplying the complete request body is easier.

To return a Draft to automatic version selection, run typeship drafts update <draft_id> --version-next null. This sends JSON null. See Draft version selection for the resulting regeneration behavior.

Regenerate and read results

typeship projects generate prj_...                          # waits for each Target's files and reports every result
typeship generations list --project-id prj_... --all            # history, newest first
typeship generations get gen_...                       # one generation with files
typeship generations list-files gen_...                 # file IDs, paths, and sizes
typeship files get file_...                         # one file, in bounded chunks
typeship spec-revisions list --spec-id spec_... --all
typeship spec-revisions get srev_...
typeship spec-revisions list-files srev_...            # source files and the resolved Spec a Generation consumed

Organization and API keys

typeship organization get
typeship api-keys list
typeship api-keys revoke key_... --force

Errors

Use --mode agent for JSON diagnostics on stderr. Request failures exit 1; usage mistakes exit 2. Inspect issues and next_steps for recovery information. See Generated CLI output and API errors.

For agents

Start by checking the credential the Typeship CLI would use:

typeship auth check --format json
typeship agent-guide --format json

For authenticated work without a credential, run typeship login --no-browser and approve the link it prints. An existing TYPESHIP_TOKEN or stored key is sufficient. Inspect Projects and their Specs and Targets before creating linked resources; the runbook gives the commands.

typeship init --all is optional machine setup: it stores credentials, installs Typeship skills, configures detected MCP clients using an environment-variable reference, and adds Typeship guidance to the repository's AGENTS.md. Use it when you want all of those changes. For one MCP client, follow its setup instructions.

Use typeship auth check to validate a credential and typeship doctor to inspect the installation.

In agent mode, errors and prompts use JSON envelopes with stable issues[].code and next_steps. Destructive commands require --force.

Useful commands:

• typeship packages generate ... --out <directory> writes a generated package to disk.
• typeship docs search "spec patches" searches the documentation.
• typeship agent-guide --format json returns the machine-readable operating contract.
• typeship help --json indexes resources and command names; typeship help <resource> <command> --json returns one command's flags, and typeship help --json --all returns every command with its flags.

See Agent mode for the full contract and agents.md for the agent runbook.