CLI reference · Kuiper docs

Conventions#

Every command prints a table or a short message. Add --json to get the raw JSON response instead.

kuiper units --json

Run kuiper --help, or kuiper <command> --help, for the exact flags of your version.

Global options#

Option	What it does
`--json`	Print raw JSON responses.
`-p`, `--project SLUG`	The project to act on. Defaults to the project set with `kuiper use`, or `KUIPER_PROJECT`.
`-u`, `--unit SLUG`	The unit to act on. Defaults to `web`.
`-V`, `--version`	Print the CLI's version.
`-h`, `--help`	Print help.

-p and -u work before or after a nested subcommand, so kuiper env set -u agent NAME=value and kuiper env -u agent set NAME=value are the same. Commands that act on a whole project take -p only. Commands that act on one unit take -p and -u.

Environment#

Variable	What it does
`KUIPER_API_URL`	The instance to talk to. Overrides the config file.
`KUIPER_TOKEN`	The API token. Overrides the config file.
`KUIPER_PROJECT`	The default project, the same as `-p`.
`XDG_CONFIG_HOME`	Where the config file lives. The default is `~/.config`.

The config file is kuiper/config.json in that directory. It holds the API URL, the token and the default project, and is readable only by you.

Command	What it does
`kuiper login`	Sign in and store the API URL and token. Opens the dashboard in your browser to approve a short code.
`kuiper login --no-browser`	Print the link to approve instead of opening a browser.
`kuiper login --token kpr_…`	Sign in with an API token. Without `--token` the token is read from standard input.
`kuiper login --api-url URL`	Sign in to a specific instance, such as a self-hosted one. The default is the saved instance, else `https://app.kuiper.sh`.
`kuiper login --browser`	Use the browser flow even when standard input is not a terminal.
`kuiper config show`	Show the saved settings. The token is never printed.
`kuiper config set api-url URL`	Point the CLI at another instance. A saved token for a different instance is dropped; one for the same instance is kept. The install script runs this for you.
`kuiper whoami`	Show the organisation the CLI is signed in to.
`kuiper use SLUG`	Set the default project.
`kuiper projects`	List projects. The same as `kuiper projects list`.
`kuiper projects create NAME`	Create a project. `--name DISPLAY` sets a display name when the first argument should stay the slug.
`kuiper projects delete SLUG`	Delete a project.

Units#

Command	What it does
`kuiper units`	List units. The same as `kuiper units list`.
`kuiper units create SLUG`	Create a unit. `--kind agent\|station\|service`, `--placement`, `--class`.
`kuiper units delete SLUG`	Delete a unit.
`kuiper status`	Show a unit's state, address, live deployment and placements.
`kuiper outputs`	List the outputs a unit exports, such as `INTERNAL_URL`, and the reference for each.
`kuiper settings`	Show or change a unit's build and run settings. They apply from the next build.
`kuiper dashboard`	Show a Station or Foundry unit's web dashboard, turn it on or off, or change its login.

kuiper settings takes --root-dir, --install-command, --build-command, --start-command, --port (0 clears it) and --dashboard-url. An empty value clears a setting.

kuiper dashboard takes --enable, --disable, --username NAME and --password -|generate|VALUE.

Deploy and build#

Command	What it does
`kuiper deploy --source DIR`	Build and deploy a directory, with no repository.
`kuiper deploy --image IMAGE`	Deploy an existing image with its `kuiper.json`.
`kuiper link`	Link a Git repository to a unit, so a push builds and deploys.
`kuiper build`	Queue a build of the linked repository.
`kuiper builds`	List a unit's builds.
`kuiper manifest validate [PATH]`	Check a `kuiper.json`. Offline.
`kuiper manifest schema`	Print the JSON Schema for `kuiper.json`. Offline.
`kuiper manifest init [DIR]`	Write the `kuiper.json` the builder would infer for a Foundry or Station app. Offline.

kuiper deploy takes --source DIR or --image IMAGE, one of them, plus --manifest PATH (default kuiper.json) and --wait, which waits until the deployment is live or fails.

kuiper link takes --repo URL, --branch (default main), --root-dir (default .), --build-env NAME=VALUE (repeat it), and --credential NAME.

kuiper build takes --ref REF and --no-deploy.

kuiper manifest init takes --station or --foundry, --out PATH (default kuiper.json) and --force.

Deployments and operations#

Command	What it does
`kuiper deployments`	List a unit's deployments.
`kuiper deployment ID`	Show one deployment, including its resolved environment with secrets masked.
`kuiper rollback DEPLOYMENT`	Redeploy a previous deployment's image and manifest.
`kuiper restart`	Apply pending variable and secret changes. Restarts at a turn boundary.
`kuiper logs`	Print a unit's logs. `--tail N` (default 200), `-f` to follow, `--deployment ID` for an earlier deployment.
`kuiper events`	Print the project's activity feed.
`kuiper usage`	Show reserved and used resources for the last 30 days.
`kuiper volumes`	List the project's persistent volumes.
`kuiper regions`	List the fleet's regions and their capacity.
`kuiper move`	Move a unit to another region or node. `--region`, `--node`, `--force`.
`kuiper migrations`	List the moves of a unit that carried its volumes, newest first.

--force on kuiper move moves a unit that has a volume without copying the data first.

Variables and secrets#

Command	What it does
`kuiper env list`	List a unit's variables with their templates.
`kuiper env set NAME=TEMPLATE…`	Set variables. Run `kuiper restart` to apply them.
`kuiper env unset NAME…`	Remove variables.
`kuiper secrets list`	List the project's secrets. Values are never shown.
`kuiper secrets set NAME=VALUE…`	Set secrets. `NAME=-` reads the value from standard input.
`kuiper secrets rm NAME…`	Remove secrets.
`kuiper shared list`	List the project's shared variables.
`kuiper shared set NAME=VALUE…`	Set shared variables. `NAME=-` reads the value from standard input.
`kuiper shared rm NAME…`	Remove shared variables.
`kuiper resources list`	List external resources and their outputs.
`kuiper resources add SLUG OUTPUT=VALUE…`	Add an external resource. `--secret OUTPUT` marks an output as secret.
`kuiper resources rename SLUG NEW_SLUG`	Rename an external resource. Templates are rewritten.
`kuiper resources rm SLUG`	Remove an external resource.

Databases and buckets#

Command	What it does
`kuiper db list`	List the project's managed databases.
`kuiper db create ENGINE SLUG`	Create a database. `ENGINE` is `postgres` or `redis`. `--size small\|medium\|large`, `--version`.
`kuiper db show SLUG`	Show one database.
`kuiper db credentials SLUG`	Print the database's connection values, masked. `--reveal` shows them.
`kuiper db restart SLUG`	Restart a database with its pinned image and existing data.
`kuiper db delete SLUG --confirm SLUG`	Permanently delete a database and its volume.
`kuiper buckets list`	List buckets.
`kuiper buckets create SLUG`	Create a bucket.
`kuiper buckets show SLUG`	Show one bucket.
`kuiper buckets credentials SLUG`	Print the bucket's access values, masked. `--reveal` shows them.
`kuiper buckets delete SLUG --confirm SLUG`	Delete an empty bucket that no variable references.

Domains#

Command	What it does
`kuiper domains list`	List every hostname of the project with its status and certificate. The alias is `ls`.
`kuiper domains add HOSTNAME`	Add a domain and print the DNS records to create. `-u UNIT`, `--redirect-to HOST`, `--www`.
`kuiper domains inspect HOSTNAME`	Show a domain's status, what DNS says and the records to create.
`kuiper domains verify HOSTNAME`	Check DNS now. `--wait` keeps checking, and `--timeout SECONDS` (default 600) gives up.
`kuiper domains claim HOSTNAME`	Move a domain from another project into this one. Needs its TXT record. `-u UNIT`, `--redirect-to HOST`.
`kuiper domains set HOSTNAME`	Serve a different unit with `-u`, or redirect with `--redirect-to HOST`. `--redirect-to none` serves the unit again.
`kuiper domains rm HOSTNAME`	Remove a domain. The alias is `remove`.

Station#

Command	What it does
`kuiper station keys`	List a Station unit's API keys and the project secret each one is kept in.
`kuiper station create-key NAME`	Create a key for another service. It is printed once. `--scope read,trigger,cancel,admin,execution,registry` (comma-separated or repeated), `--no-secret`.
`kuiper station revoke-key ID`	Revoke a key. Its secret is removed too, unless a variable still references it.

Registries, Git and tokens#

Command	What it does
`kuiper registry list`	List the project's registry credentials.
`kuiper registry add REGISTRY`	Add or replace credentials for a registry host. `--username` is required. The password is read from standard input unless you pass `--password`.
`kuiper registry rm REGISTRY`	Remove credentials for a registry.
`kuiper git list`	List the credentials your organisation can build with.
`kuiper git add-token NAME`	Add a personal access token. `--token`, `--host` (default `github.com`), `--username`. The token is read from standard input unless you pass `--token`.
`kuiper git rm NAME`	Remove a credential.
`kuiper git github`	Say whether the GitHub App is available. Connect it from the dashboard.
`kuiper tokens list`	List the organisation's API tokens, revoked ones included. `*` marks the one in use.
`kuiper tokens create NAME`	Create an API token. It is printed once.
`kuiper tokens revoke ID`	Revoke a token. The organisation's last active token cannot be revoked.

Operators#

kuiper admin is for the people who run a Kuiper installation. It talks to the admin API, which is reachable only over the operator's private network. It takes --admin-url (or KUIPER_ADMIN_URL, default http://127.0.0.1:8081) and --admin-token (or KUIPER_ADMIN_TOKEN).

Command	What it does
`kuiper admin nodes`	List nodes with their state, region and capacity.
`kuiper admin register-node NAME`	Register a node and print its ID and token. `--region`, `--label KEY=VALUE`.
`kuiper admin set-node NODE`	Set a node's region and labels.
`kuiper admin drain NODE`	Move every placement off a node.
`kuiper admin cordon NODE`	Keep new placements off a node.
`kuiper admin uncordon NODE`	Allow placements on a node again.
`kuiper admin reset-node-key NODE`	Forget a node's pinned mesh key so a reinstalled `kuiperd` can register a new one.
`kuiper admin mesh-probe SOURCE TARGET`	Send a few megabytes between two nodes and report whether both ends agree. `--no-wait`.
`kuiper admin transfers`	List node-to-node transfers. `--state open\|all\|done\|failed`.
`kuiper admin edges`	List the edges the control plane pushes routes to.
`kuiper admin add-edge NAME`	Register an edge. `--caddy-admin-url URL` is required. `--region`, `--serves-api`.
`kuiper admin remove-edge EDGE`	Remove an edge.
`kuiper admin routes`	Show the current routes.
`kuiper admin headroom`	Show capacity and whether to add a node.
`kuiper admin allowlist [CAPABILITY IMAGE…]`	Show the images each capability may run, or set them.
`kuiper admin usage`	Show fleet usage.
`kuiper admin create-org NAME`	Create an organisation and print its first token.
`kuiper admin tokens --org ORG`	List an organisation's API tokens.
`kuiper admin create-token --org ORG`	Create another token for an organisation. `--name`.
`kuiper admin revoke-token --org ORG TOKEN_ID`	Revoke an organisation's token, even its last one.
`kuiper admin domains`	List every domain on this Kuiper. The same as `kuiper admin domains list`.
`kuiper admin domains add HOSTNAME`	Add a platform domain. `--org`, `--project`, `--unit`, `--redirect-to`.
`kuiper admin domains rm HOSTNAME`	Remove a domain. The alias is `remove`.
`kuiper admin domains rehome --from DOMAIN`	Move every app under an old apps domain to the current one. The old names keep working as redirects.
`kuiper admin github`	Show the GitHub App's status and its linked installations.
`kuiper admin github-link --org ORG --installation ID`	Link a GitHub App installation to an organisation by hand.