CLI reference

Every command, every flag, and how the config file works. The CLI is a thin client over the HTTP API; nothing here is hidden from the API or the dashboard.

Install

$ npm install -g @flagrship/cli
$ flagrship --help

Requires Node 20.12 or later. A single 121 KB file with one dependency.

Global options

These work on every command.

Option	What it does
-e, --env <name>	Target a different environment. Selects the key stored for that environment in `.flagrship.json`; there is no way to send an environment to the server.
--json	Print the raw API response as JSON instead of a table. For scripts.
--verbose	Print each request and response status to stderr.
-v, --version	Print the CLI version.

Commands

init

Store an API key. The CLI calls the API to verify the key and learn which environment it belongs to, then writes the config file and adds it to .gitignore. Run it once per environment.

$ flagrship init --key <api-key>
 
# or keep the key out of your shell history
$ export FLAGRSHIP_API_KEY=sk_test_...
$ flagrship init
$ cat key.txt | flagrship init --key -

Option	What it does
-k, --key <api-key>	The key to store. `-` reads it from stdin. Falls back to `$FLAGRSHIP_API_KEY`. A key passed on the command line is visible to other processes via `ps` and lands in your shell history, so prefer the other two.
--api-url <url>	API base URL. Default `https://api.flagrship.dev`. Use `http://127.0.0.1:3000` against a local API.
--allow-custom-host	Required to send the key to a host that is not flagrship.dev or a local address.
--default	Make this key's environment the default. The first key stored is the default automatically.

create

$ flagrship create <key> [--name <name>] [--description <text>]

Creates the flag in every environment, disabled and at 0%. The key must be 3 to 120 characters of lowercase letters, digits, and hyphens, starting and ending alphanumeric. If you omit --name, it is derived from the key: new-checkout becomes New Checkout.

list

$ flagrship list [--search <text>]
$ flagrship ls

Every flag in the current environment, with state and last change. --search matches key or name.

KEY           STATE      NAME          CHANGED
dark-mode     ON    0%   Dark Mode     1h ago
new-checkout  ON   25%   New Checkout  12s ago

status

$ flagrship status <key>

Full state for one flag in the current environment, including lock reason if locked.

enable / disable

$ flagrship enable <key>
$ flagrship disable <key>

enable preserves the rollout percentage: a flag that was at 25% comes back at 25%. disable is the kill switch and resets the percentage to 0. The previous percentage is in the audit log, which is what rollback reads.

rollout

$ flagrship rollout <key> <percentage>

Set the percentage of users who see the flag, 0 to 100. The flag must be enabled first. The CLI validates the number before making a request.

rollback

$ flagrship rollback <key>

Undo the most recent change to this flag in this environment. A second rollback undoes the first. Refused with a 409 if the flag has never been changed.

lock / unlock

$ flagrship lock <key> --reason <text>
$ flagrship unlock <key>

Both require an admin key. A locked flag rejects every other mutation with a message that includes the reason. Locking an already-locked flag is a 409, as is unlocking one that is not locked.

log

$ flagrship log <key>

The last 50 audit entries for the flag, newest first: when, action, what changed, and who did it.

The config file

.flagrship.json lives in your project root and the CLI finds it by walking up from the current directory, the same way git finds .git. It holds one key per environment.

.flagrship.json

1{
2  "apiUrl": "https://api.flagrship.dev",
3  "defaultEnvironment": "staging",
4  "keys": {
5    "staging": "sk_test_your_staging_key",
6    "production": "sk_live_your_production_key"
7  }
8}

On Windows the mode is a no-op and the file inherits the directory's permissions. Keys are revocable: if one may have leaked, run flagrship keys revoke and issue a new one rather than hunting for copies.

Errors and exit codes

Every failure exits with code 1 and a one-line message on stderr. API errors are printed verbatim with the request ID, so support can find the exact request.

$ flagrship rollout new-checkout 50
error: Flag "new-checkout" is locked: CVE-2026-1234. An admin must unlock it first.
  request id: 6d5ea4be-705c-45ef-afe7-2a6d65b1bef5

Network failures and 5xx responses are retried three times with backoff (1s, 2s, 4s). 4xx responses are never retried: the request itself is wrong, and three more copies of it will not help. A 429 is a 4xx and is not retried either - the message says how long to wait.

--verbose prints the method, URL, and response status to stderr. It never prints the API key, the authorization header, or a request body.

Previous← Concepts NextJavaScript →