CLI

Overview

shipd is the command-line interface for config as code. It syncs TypeScript, Go, or JSON flag configs with the server, generates flag types, and runs snapshot recovery operations. Every command supports --json. Use --yes or --ci to skip confirmation prompts for unattended runs.

npm install -g @shipdit/cli   # Node.js 22.12 or later
shipd --help

Package: @shipdit/cli. Binary: shipd.

Global options

Global options go before or after the command name and apply to every command.

Option	Type	Default	Description
`--json`	boolean	`false`	Print results as JSON on stdout. Errors print as JSON on stderr.
`--yes`	boolean	`false`	Skip confirmation prompts.
`--ci`	boolean	`false`	Same as `--yes`.
`--api-url <url>`	string	the URL saved by `shipd login`; `http://localhost:8000` if none	Control-plane API origin. See Configuration precedence.
`--org <slug>`	string	—	Organization slug or ID. With an API key or token, this is a guard: it must match the credential’s organization, and it never switches organizations.
`--project <slug>`	string	the credential’s project	Project slug or ID.
`--env <slug>`	string	the credential’s environment	Environment slug or ID.
`--config <path>`	string	`.shipd/config.json`	Project settings file. See `.shipd/config.json`.
`--flags-config <path>`	string	Auto-discovered TypeScript, Go, or JSON config	Path to `shipd.config.ts`, `shipd.config.go`, or `shipd.config.json`.

Confirmation is also skipped when CI=1, CI=true, or SHIPD_CI=1. Without any of these, a command that needs confirmation and has no TTY (for example, a CI job) is cancelled with exit code 1.

Configuration precedence

Each setting resolves from the first source that has it:

Setting	1	2	3	4	5
API URL	`--api-url`	`SHIPD_API_URL`	`.shipd/config.json` `apiUrl`	global `config.json` `apiUrl`	`apiUrl` in `credentials.json` (saved by `shipd login`)
Credential	`SHIPD_API_KEY`	`credentials.json`	—	—	—
Organization	`--org`	`SHIPD_ORG`	`.shipd/config.json` `org`	global `config.json` `org`	—
Project	`--project`	`SHIPD_PROJECT`	`.shipd/config.json` `project`	global `config.json` `project`	the credential’s bound project
Environment	`--env`	`SHIPD_ENV`	`.shipd/config.json` `env`	global `config.json` `env`	the credential’s bound environment
Flags file	`--flags-config`	`.shipd/config.json` `configFile`	Auto-discovered `shipd.config.ts`, `.go`, or `.json` in the project root	—	—
Types output	`.shipd/config.json` `typesOut`	TypeScript: `src/generated/flags.ts`; Go: `internal/flags/flags_gen.go`	—	—	—

The project root is the nearest directory, walking up from the current directory, that contains shipd.config.ts, shipd.config.go, shipd.config.json, or .shipd/config.json. Relative configFile and typesOut paths resolve against the current directory, so run shipd from the project root. If no source sets the API URL, shipd login uses https://api.useshipd.com and saves it to credentials.json. Every other command falls back to http://localhost:8000.

On a machine that never ran shipd login, such as a CI runner using SHIPD_API_KEY, commands call http://localhost:8000 unless you set SHIPD_API_URL=https://api.useshipd.com or pass --api-url https://api.useshipd.com.

Credentials

File	Contents	Written by
`~/.config/shipd/credentials.json`	`apiKey` (the management API key) and `apiUrl`	`shipd login`; removed by `shipd logout`
`~/.config/shipd/config.json`	Default `org`, `project`, `env` (and optional `apiUrl`, `appUrl`)	`shipd login`

Both files are written with mode 0600. When XDG_CONFIG_HOME is set, the directory is $XDG_CONFIG_HOME/shipd instead of ~/.config/shipd. SHIPD_API_KEY overrides the stored key. It accepts a management API key (shipd_mgmt_…) or a service account token (shipd_sa_…). SDK keys (shipd_sdk_…) do not work with the CLI. See SDK keys, management API keys, and service account tokens.

Environment variables

Variable	Equivalent	Description
`SHIPD_API_KEY`	—	Management API key or service account token. Overrides `credentials.json`.
`SHIPD_API_URL`	`--api-url`	Control-plane API origin. Set to `https://api.useshipd.com` in CI.
`SHIPD_ORG`	`--org`	Organization guard.
`SHIPD_PROJECT`	`--project`	Project slug or ID.
`SHIPD_ENV`	`--env`	Environment slug or ID.
`SHIPD_CI`	`--ci`	`1` skips confirmation.
`CI`	`--ci`	`1` or `true` skips confirmation.
`XDG_CONFIG_HOME`	—	Moves the global config directory.

JSON output

With --json, results print to stdout as pretty-printed JSON. Errors print to stderr as one line:

{ "error": { "code": "conflict", "message": "Flag \"search-variant\" changed remotely (expected version 4, remote 5). Pull and retry, or pass --force.", "details": {} } }

code is the control-plane error code, or a CLI-side code. See Errors. Authenticates the CLI through browser device authorization and stores a management API key.

shipd login [--api-url <url>]

Option	Type	Default	Description
`--api-url <url>`	string	resolved as in Configuration precedence, else `https://api.useshipd.com`	API origin to authenticate against.

Behavior.

Prints a verification URL and a one-time code, then polls until you approve or the code expires.
In the browser you choose an organization, a project, and an environment. The key is bound to exactly those three.
Writes the key and API URL to credentials.json.
Saves the organization, project, and environment slugs as defaults in the global config.json. Later commands need no --project or --env.

Run shipd login again to switch the default project or environment.

Output

Open the following URL in your browser and enter the code:

  https://app.useshipd.com/auth/device/code?user_code=WDJB-MJHT

  Code: WDJB-MJHT

Waiting for approval…
Logged in successfully (fieldkit / web-app / production).

With --json, the code and URL print to stderr as JSON and the result prints to stdout. Exit codes. 0 on success. 1 if authorization is denied, expires, or times out. Related: shipd logout · shipd whoami · Keys

shipd logout

Deletes credentials.json.

shipd logout

Default org, project, and env in the global config.json are kept. The key is not revoked on the server; revoke it in the dashboard under Management keys. Exit codes. 0.

shipd whoami

Prints the identity behind the current credential.

shipd whoami

Output

API key: key_01
Organization: fieldkit (org_01)
Project: web-app (proj_01)
Environment: production (env_01)

The first line is API key: <id> for a shipd login key, Service account: <id> (token <id>) for a service account token, or User: <name> <email> for a user session. Project and environment lines appear only when the credential is bound to them. Exit codes. 0, or 1 if unauthenticated.

shipd push

Plans the changes needed to make the server match shipd.config.ts, asks for confirmation, applies them, and regenerates flag types.

shipd push [--prune] [--force] [--adopt]

Option	Type	Default	Description
`--prune`	boolean	`false`	Archive remote flags that are missing from `shipd.config.ts`.
`--force`	boolean	`false`	Apply even if a flag changed on the server since the plan was computed. Audited.
`--adopt`	boolean	`false`	Deprecated no-op. Accepted for older scripts.

Also uses the global --yes / --ci, --project, --env, --flags-config, and --json.

Sequence

Load and validate the selected TypeScript, Go, or JSON flag config (see validation rules).
Ask the server for a plan against the target project and environment. Print it.
If the plan is empty, print Nothing to push. and exit 0. Types are not regenerated.
Confirm (Apply this plan? [y/N]) unless --yes, --ci, or CI is set.
Apply the plan with the flag versions seen in step 2.
Regenerate types to typesOut from the local file.

Output

Plan:
  + create flag "new-checkout"
  ~ update flag "search-variant"
      tags: ["search"] -> ["search","experiment"]
  ~ update flag "max-retries"
      default: 3 -> 5

Note: definition changes (type, variants, tags, lifecycle, description) apply to all environments.
Note: definition/ownership changes apply to all environments (requires production permission).
Apply this plan? [y/N] y
Applied 3 change(s).
Wrote types for 4 flag(s) to /home/dev/web-app/src/generated/flags.ts

What each change does

Plan line	When	Effect
`+ create flag`	Key is in the file, not on the server	Creates the flag with `managedBy: code`. In the target environment it is enabled and its fallthrough is set to `default`. In every other environment it is disabled with a disabled fallthrough, so SDKs there receive the type’s zero value (`false`, first variant, `0`, `{}`).
`~ update flag`	Definition fields or `default` differ	Updates project-global fields, then rewrites the target environment’s fallthrough if `default` changed. Sets `managedBy: code`.
`- archive flag`	Key is on the server, not in the file, and `--prune` is set	Archives the flag. Archive is not a hard delete.
(warning only)	Key is on the server, not in the file, no `--prune`	Left alone. The CLI prints `Warning: N remote flag(s) not in local config (pass --prune to archive)`.

Field scope

Field	Scope	Written by push to
`type`, `variants`, `description`, `tags`, `deprecated` (lifecycle)	Project-global	The flag definition, for every environment
`default`	Per environment	The fallthrough of the target environment only

Changing default replaces the target environment’s fallthrough with that fixed value, including a weighted fallthrough set in the dashboard. Rules and the Enabled in <env> switch are not changed. Because the plan compares against the live fallthrough, pushing a file that still has an old default reverts a fallthrough edited in the dashboard. Run shipd pull or read the default: line in the plan first. Targeting rules, rollouts, and the enabled switch are never in shipd.config.ts. Set them in the dashboard. See Targeting.

managedBy

managedBy (code or dashboard) records which surface last changed a flag. It is attribution, not a lock: shipd push updates dashboard-edited flags, and the dashboard edits code-managed flags. --adopt does nothing.

Permissions

Push checks permissions against the whole plan. The credential needs:

Action	Required when
`flag.update`	Always.
`flag.create`	The plan creates flags.
`flag.archive`	The plan archives flags (`--prune`).
`flag.production.toggle`	The target environment is production, or the plan creates, archives, or changes definition fields.
`flag.state.update`	The plan only changes `default` in a non-production environment.

A management API key from shipd login acts with your role in its project. Service account tokens need these actions as scopes; see Sync flags in CI for scope names. Service account tokens bound to a single environment cannot create, update, or archive flags because those changes are project-wide; bind CI tokens to the project.

Conflicts

Apply is a compare-and-swap. The CLI sends the definition version and environment-state version of every flag it plans to change. If either changed on the server after the plan, the server rejects the whole push with 409 conflict (exit 3) and applies nothing:

Error: Flag "search-variant" changed remotely (expected version 4, remote 5). Pull and retry, or pass --force.

--force skips the version check, applies the local definitions over the remote ones, and records the push in the audit log with the reason Forced CAS override. It does not bypass permissions or approvals. See Why did shipd push return a conflict?.

Approvals

When an approval policy covers the target environment:

A default change, or the enable-and-fallthrough step of a new flag, is queued as an approval request instead of applied. Push exits 5 and prints N environment change(s) queued for approval. The queued state is not live.
Changes that no policy matches in the same push still apply.
A second push for a flag that already has a pending request in that environment fails with 409 conflict (exit 3).
A definition change (create, archive, or a project-global field) when a policy covers any environment in the project cannot be submitted for review. The whole push fails with 409 conflict (exit 3) and nothing applies.

--yes, --ci, and --force never approve anything.

Limits

At most 500 flags per push. Larger files fail validation.
Flag keys must be unique.
Apply is transactional. A conflict, permission error, or invalid flag applies nothing and queues no approval requests.
Creating flags counts against your plan’s flag allowance. See Usage and limits.

JSON output

{
  "plan": { "creates": [], "updates": [], "archives": [], "unlinked": [], "conflicts": [] },
  "remoteOnly": [],
  "forced": false,
  "approvalRequests": ["apr_01"],
  "outcome": "pending_approval",
  "types": { "written": "/home/dev/web-app/src/generated/flags.ts", "flagCount": 4 }
}

outcome is applied or pending_approval. When the plan is empty, only plan and remoteOnly are printed.

Example

shipd push --yes --project web-app --env staging

Exit codes. 0 applied or nothing to push · 1 error, or confirmation declined · 3 conflict · 5 some changes are pending approval. If generated output cannot be written after apply, the remote changes remain applied. Fix the output path or permissions and run shipd types gen to regenerate the local output. Related: shipd diff · defineFlags · Push, pull, and diff

shipd diff

Prints the plan shipd push --prune would apply, without changing anything.

shipd diff [--exit-code]

Option	Type	Default	Description
`--exit-code`	boolean	`false`	Exit `2` when the plan is not empty, `4` when it contains unlinked flags.

Behavior. diff needs only flag.read, so any credential that can read the environment works, including a shipd login key. Remote flags missing from the file appear as - archive flag lines, and the CLI adds Note: N remote flag(s) are missing locally. shipd push leaves them alone unless you pass --prune. They count as drift for --exit-code.

Output

Plan:
  ~ update flag "max-retries"
      default: 3 -> 5
  - archive flag "welcome"

A clean diff prints No drift. With --json, prints { creates, updates, archives, unlinked, conflicts, remoteOnly }.

Example

shipd diff --exit-code --project web-app --env production

Exit codes. 0 no drift, or --exit-code not set · 1 error · 2 drift (with --exit-code) · 4 unlinked (with --exit-code). Current servers do not report unlinked flags because managedBy is not a lock. Related: shipd push · Sync flags in CI

shipd pull

Overwrites the selected flag config with the flags on the server, preserving TypeScript, Go, or JSON format, then regenerates TypeScript types or Go accessors. Go input defaults to Go output unless typesLanguage overrides it.

shipd pull

Behavior.

Writes every non-archived flag in the project. Each flag’s default is the target environment’s fallthrough. A disabled fallthrough becomes the type’s zero value, and a weighted fallthrough becomes its first variation. Go and JSON preserve the disabled state; TypeScript definitions currently cannot represent it.
The file is regenerated from scratch. Comments, formatting, helper code, and custom imports are lost.
Needs only flag.read.

Output

Wrote 4 flag(s) to /home/dev/web-app/shipd.config.ts
Wrote types for 4 flag(s) to /home/dev/web-app/src/generated/flags.ts

Commit or stash the selected flag config (shipd.config.ts, shipd.config.go, or shipd.config.json) before you pull.

Exit codes. 0 or 1. If writing generated output fails, the config may already have been replaced. Fix the output path or permissions and run shipd types gen to regenerate it. Related: shipd push · Why did shipd push return a conflict?

shipd types gen

Writes TypeScript types or Go accessors from the local TypeScript, Go, or JSON flag config. Does not contact the server. Loading shipd.config.go requires Go 1.23+ on PATH; Go input selects Go output unless typesLanguage or --language says otherwise.

shipd types gen [-o <path>] [--language typescript|go] [--package <name>]

Option	Type	Default	Description
`-o, --out <path>`	string	Configured output, or the selected language’s default	Output file. Parent directories are created.
`--language <language>`	`typescript` or `go`	`typesLanguage`, else inferred from the config file	Output language for this invocation.
`--package <name>`	string	`typesPackage`, else `flags`	Package name for generated Go output.

Output

Wrote types for 4 flag(s) to /home/dev/web-app/src/generated/flags.ts

Exit codes. 0, or 1 if the file, language, package name, or generated identifiers are invalid. Related: Generate flag types · Generated types Go generation needs no credentials:

shipd types gen --language go --out internal/flags/flags_gen.go

If --language switches away from the configured language, its default output path is used unless --out is supplied. Set typesLanguage in project settings to select Go output for push and pull too.

shipd flags list

Lists flags in the project, one per line: key, type, lifecycle, managedBy.

shipd flags list

Output

new-checkout	boolean	active	code
search-variant	variant	active	dashboard

Needs a project (--project or a project-bound credential). Exit codes. 0 or 1.

shipd flags create

Creates one flag without editing shipd.config.ts.

shipd flags create --key <key> [--type <type>] [--variants <names>] [--name <name>] [--description <text>]

Option	Type	Default	Description
`--key <key>`	string	required	Flag key.
`--type <type>`	`boolean` \| `variant` \| `number` \| `json`	`boolean`	Flag type.
`--variants <names>`	string	—	Comma-separated variant names. Repeatable. Required with `--type variant`; rejected with any other type. Duplicates are removed.
`--name <name>`	string	the key	Display name.
`--description <text>`	string	—	Description.

Behavior. The flag is created in every environment with a disabled fallthrough. Requires flag.create. Add the flag to shipd.config.ts (or run shipd pull) so the next push does not report it as remote-only.

Example

shipd flags create --key search-variant --type variant --variants control,semantic,hybrid

Exit codes. 0 or 1.

shipd flags archive

Archives a flag after confirmation.

shipd flags archive --key <key>

Option	Type	Default	Description
`--key <key>`	string	required	Flag key.

Requires flag.archive. Archive is not a hard delete. Exit codes. 0, or 1 (including when confirmation is declined).

shipd projects list

Lists projects in the organization: slug, name, ID.

shipd projects list

Exit codes. 0 or 1.

shipd environments list

Lists environments in the project: slug, name, production or the environment type, ID.

shipd environments list

An environment-bound credential sees only its own environment. Exit codes. 0 or 1.

shipd snapshots publish

Publishes the environment’s current configuration again when an earlier publication failed.

shipd snapshots publish

Ordinary flag changes publish automatically. Check Troubleshooting before using this recovery command. Requires snapshot.publish. See Publish a snapshot.

shipd snapshots outbox

Lists publication jobs for the environment. Use this to check whether a saved change is waiting to publish or has failed. dead_lettered means automatic retries have stopped; contact support if failures persist.

shipd snapshots outbox [--status <status>]

Option	Type	Default	Description
`--status <status>`	`pending` \| `processing` \| `published` \| `failed` \| `dead_lettered`	all	Filter by status.

Output

#118 v42 dead_lettered attempts=8 — KV write failed

Requires snapshot.publish.

shipd snapshots requeue

Retries publication jobs that stopped after repeated failures. Use this after the cause of a publication failure has been resolved, or when support directs you to retry.

shipd snapshots requeue

Output

Requeued 1 dead-lettered row(s).

Requires snapshot.publish.

shipd snapshots rebuild

Requests a rebuild of the current published configuration without changing its version. Use this when support asks you to rebuild an environment; it does not roll back or change flag values.

shipd snapshots rebuild [--project]

Option	Type	Default	Description
`--project`	boolean	`false`	Rebuild every environment in the project instead of one.

Requires snapshot.publish. Environment-bound credentials cannot rebuild a whole project.

shipd snapshots publications

Lists publication history for the environment. Use the version and time to check whether a recent change published, and share publication details with support when troubleshooting update delivery.

shipd snapshots publications

Requires snapshot.read (admins and owners), which project- or environment-bound credentials cannot use. snapshot.publish is held by every role that can update flags (editor, admin, owner).

Exit codes

This is the single list of shipd exit codes. Causes and fixes are in Errors.

Code	Meaning	Returned by
`0`	Success, nothing to do, or no drift	all
`1`	General error: authentication, permission, validation, not found, network, usage error, or declined confirmation	all
`2`	Drift	`diff --exit-code`
`3`	Conflict (`409`): stale version, pending approval request exists, or unsupported protected operation	`push`, and any command that receives `409`
`4`	Unlinked flags	`diff --exit-code`
`5`	Some changes are pending approval; they are not live	`push`

Related: defineFlags and config files · Errors · Sync flags in CI

SDK setup

SDK reference

Config and CLI reference

Overview

Global options

Configuration precedence

Credentials

Environment variables

JSON output

shipd logout

shipd whoami

shipd push

Sequence

What each change does

Field scope

managedBy

Permissions

Conflicts

Approvals

Limits

JSON output

shipd diff

shipd pull

shipd types gen

shipd flags list

shipd flags create

shipd flags archive

shipd projects list

shipd environments list

shipd snapshots publish

shipd snapshots outbox

shipd snapshots requeue

shipd snapshots rebuild

shipd snapshots publications

Exit codes

​Overview

​Global options

​Configuration precedence

​Credentials

​Environment variables

​JSON output

​shipd login

​shipd logout

​shipd whoami

​shipd push

​Sequence

​What each change does

​Field scope

​managedBy

​Permissions

​Conflicts

​Approvals

​Limits

​JSON output

​shipd diff

​shipd pull

​shipd types gen

​shipd flags list

​shipd flags create

​shipd flags archive

​shipd projects list

​shipd environments list

​shipd snapshots publish

​shipd snapshots outbox

​shipd snapshots requeue

​shipd snapshots rebuild

​shipd snapshots publications

​Exit codes

Overview

Global options

Configuration precedence

Credentials

Environment variables

JSON output

shipd login

shipd logout

shipd whoami

shipd push

Sequence

What each change does

Field scope

managedBy

Permissions

Conflicts

Approvals

Limits

JSON output

shipd diff

shipd pull

shipd types gen

shipd flags list

shipd flags create

shipd flags archive

shipd projects list

shipd environments list

shipd snapshots publish

shipd snapshots outbox

shipd snapshots requeue

shipd snapshots rebuild

shipd snapshots publications

Exit codes