klops CLI
Everything the web interface does, from a terminal or a script.
On this page
What it is
klops is the klickops command line. It talks to the same REST API the web interface uses, so anything you can click, you can script. There is no second feature set and nothing the UI can do that the CLI cannot.
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
klops auth login --server https://klickops.example.comThat 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 apps logs web --project shop --follow
klops db query orders-db --project shop -c "select count(*) from orders"
klops apps deploy web --image nginx:1.27-alpine --port 80 --project shopEvery 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 | Reading, with more columns. |
Colour is dropped automatically when the output is not a terminal, so klops apps list -o json \| jq never sees escape codes.
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 |
The useful consequence: 3 and 4 are different questions. A 3 in CI means the token needs renewing; a 4 means it needs more rights.
Limits and gotchas
- 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.
Related
- API tokens for authenticating a script.
- MCP server if the thing driving klickops is an AI assistant rather than a script.