klops CLI

Everything the web interface does, from a terminal or a script.

View .md Reviewed against 2026.9.10

On this page

What it is
When you'd use it
Signing in
The shape of a command
Where settings come from
Exit codes
Limits and gotchas
Related

What it is

klops is the klickops command line. It talks to the same REST API the web interface uses, so almost anything you can click, you can script. A few things are still web-only: filing and answering support requests (klops support reads them), live traffic, the activity feed, and your own sign-in methods and email settings.

It talks to klickops and to nothing else. No kubeconfig, no direct database connections, no kubectl on your machine. That is deliberate: access control, audit and TLS all stay in one place, and your laptop needs no cluster credentials.

When you'd use it

A deploy from a script, or from your own CI.
Reading logs or running a query without opening a browser.
Doing the same thing across ten projects without twenty clicks.

Signing in

Install it with the one-line command under Resources, CLI & MCP in klickops, which points it at your server.

klops auth login --server https://klickops.example.com

Your browser opens on the sign-in page. Type the code your terminal shows, check the IP address and device the page lists, then approve. If you did not just start the sign-in yourself, deny it. On a machine without a browser, add --device: it prints a code you approve from any browser where you are signed in. A sign-in lasts at most seven days, and klops auth logout ends it on the server too.

That writes ~/.klickops/config.yaml with permissions 0600, and refuses to read the file if the permissions are looser. For CI, skip the login and set KLICKOPS_SERVER and KLICKOPS_TOKEN instead, using an API token rather than your own account.

The shape of a command

Commands read as noun then verb.

klops apps list --project shop
klops logs web --project shop --follow
klops db query orders-db --project shop -- "select count(*) from orders"
klops apps deploy web --image nginx:1.27-alpine --port 80 --project shop

Every read command takes -o, which is what makes it scriptable:

Format	For
`table`	Reading. The default.
`json`	Piping into `jq`.
`yaml`	Diffing, or feeding something else.
`name`	Just the names, for a shell loop.
`wide`	Accepted, but today prints the same columns as `table`.

klops prints no colour or escape codes, so klops apps list -o json | jq always gets clean output.

Where settings come from

Flag beats environment variable beats config file beats default. So a --project on the command line wins over KLICKOPS_PROJECT, which wins over the current context in ~/.klickops/config.yaml.

Variable	Sets
`KLICKOPS_SERVER`	Which klickops to talk to
`KLICKOPS_TOKEN`	The token to authenticate with
`KLICKOPS_ORG`	Default organization
`KLICKOPS_PROJECT`	Default project

Exit codes

Scripts depend on these, so they are stable.

Code	Means
`0`	Success
`1`	Something went wrong
`2`	You used the command wrong
`3`	Not signed in, or the token expired
`4`	Signed in, but not allowed
`5`	Not found
`6`	Already exists
`7`	The request was too large

The useful consequence: 3 and 4 are different questions. A 3 in CI means the token was revoked or mistyped; a 4 means it needs more rights.

Limits and gotchas

Anything destructive asks first. Deleting, revoking, restoring over or rolling back something asks for a yes on a terminal. A script has no one to answer, so the command exits with 2 unless you pass --yes (or -y).
There is no cache. Every command asks the server, because stale state bites worse than a round trip.
The config file is refused if its permissions are loose. It holds a token, so a world-readable file is treated as a mistake rather than a preference.
A token belongs to an organization, not to you. Scripts should use one rather than your personal session, so a person leaving does not break the pipeline. See API tokens.

API tokens for authenticating a script.
MCP server if the thing driving klickops is an AI assistant rather than a script.