Typeship CLI
Drive Typeship from a terminal or a pipeline: generate packages, manage projects, trigger regeneration, and read results as JSON.
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
Typeship CLI executable archives are not currently published. Use the web generator or public HTTP API without installing the Typeship CLI.
When an executable release is available on the Typeship CLI releases page, select your operating system and architecture, verify the downloaded archive against that release's checksums.txt, extract it, and place typeship (typeship.exe on Windows) on your PATH.
typeship --versionThe 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/organizationtypeship 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 can run for up to 5 minutes on the server. The Typeship CLI uses a fixed 60-second request timeout and has no --timeout or TYPESHIP_TIMEOUT override, so longer requests can time out in the client.
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
Saving changed patches with typeship specs update starts generation for active Targets when auto_generate is enabled. The command returns the saved Spec without waiting for the runs; list Generations to observe them. With automatic generation disabled, run typeship projects generate after saving patches. See Spec patches.
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 consumedOrganization and API keys
typeship organization get
typeship api-keys list
typeship api-keys revoke key_... --forceErrors
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 jsonFor 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 can store a credential supplied with -k. Add --agents-md to write Typeship guidance to the repository's AGENTS.md. It does not install skills or configure MCP clients. Follow the agent setup instructions for those tasks.
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 jsonreturns the machine-readable operating contract.typeship help --jsonindexes resources and command names;typeship help <resource> <command> --jsonreturns one command's flags, andtypeship help --json --allreturns every command with its flags.
See Agent mode for the full contract and agents.md for the agent runbook.