typeship CLI

The typeship command is the CLI for typeship's own API. It ships in the typeship-ax npm package and is generated by typeship from its own spec, so it behaves exactly like the CLIs typeship generates for your API: flags from the spec, JSON on stdout, exit codes 0, 1, and 2, login, config, docs, completion, and the rest. Everything on the CLI page applies. This page covers what is specific to typeship's commands.

Install

npm install -g typeship-ax
typeship --version

The package is typeship-ax; the command it installs is typeship. The bare name was taken on npm, and a registry name is claimed against every package in the world while a command is only claimed against your PATH, so the two differ here and only here. Everything else is typeship: the command, TYPESHIP_TOKEN, ~/.config/typeship/, and the typeship-mcp server. npx -y typeship-ax@latest <command> runs it without installing.

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 /v1/me

The first form needs no key in hand: the console page at /cli-auth asks you to approve typeship CLI on <host> (and, if you belong to several organizations, which one the key is for), and the typeship CLI stores the key it gets back, named after the machine so you can revoke it under api keys later. typeship logout revokes a key minted this way as it removes it; a key you pasted is left alone, since it was not the typeship CLI's to end. Credentials are stored in ~/.config/typeship/credentials.json. TYPESHIP_TOKEN and --token win over stored credentials, so CI needs no login step.

Generate a package

Once logged in (or with TYPESHIP_TOKEN set):

typeship generate run \
  --spec '{"url":"https://api.acme.example.com/openapi.json"}' \
  --platforms '["sdk","cli","mcp"]' \
  --language typescript > result.json

--spec accepts {"url": ...} or {"inline": "<spec text>"}. --language is typescript, python, or go. --config '{...}' takes the same config object as a project. Output is the generation result: files, warnings, and meta.

Manage projects

typeship projects list --all
typeship projects create --name "Acme API" \
  --spec-url https://api.acme.example.com/openapi.json \
  --platforms '["sdk","cli"]' \
  --languages '["typescript","python"]' \
  --auto-regen true
typeship projects get prj_...
typeship projects update prj_... --spec-patches '[{"op":"set","path":"/info/title","value":"Acme"}]'
typeship projects delete prj_...

Object-valued fields (--destinations, --package-names, --config) take JSON. --data '<json>' supplies the whole body when that is easier.

Regenerate and read results

typeship projects generate prj_...                          # one generation per language, with files
typeship projects list-generations prj_... --all            # history, newest first
typeship generations get gen_...                            # one generation with files
typeship generations get-file gen_... --path src/index.ts   # a single file, for large outputs
typeship spec-versions list prj_... --all
typeship spec-versions get-content spec_...                 # the raw spec a generation came from

Account and usage

typeship usage retrieve
typeship account me
typeship api-keys list
typeship api-keys revoke key_... --force

usage retrieve includes requests: who called the API in the last 30 days by surface (cli, mcp, sdk, http) and by agent harness, from the User-Agent the typeship CLI and MCP server send (typeship-cli/1.0.0 (typeship; harness=claude-code; agent)). It carries no secrets and nothing else is collected.

For agents

One line sets a machine up. With no key anywhere, init starts the browser approval itself (an agent prints the link for you and waits), so the first command on a new machine is also the only one:

typeship init --all                # approve in the browser; or -k ak_... with a key in hand

It stores the key, installs the typeship skills, writes the hosted MCP endpoint into every agent client on the machine (the key as an env reference, never a literal), and adds a typeship block to AGENTS.md. Then typeship agent-guide --format json explains the conventions, typeship auth check --live confirms the key, and typeship doctor checks the rest.

Errors are one JSON envelope on stderr with a stable issues[].code and next_steps; deletes need --force; --mode agent (or no terminal) turns every prompt into an envelope. typeship generate run ... --out sdk/ writes a generated package straight into a directory. typeship docs search "spec patches" searches these docs from the terminal. The full contract is on the CLI platform page; the runbook an agent reads first is typeship.dev/agents.md.