CLI reference
kaviris <command> [flags]
Use it in a terminal, in scripts, and from any coding agent that can run commands: the fallback whenever the agent has no MCP, or its MCP sign-in does not work.
Install
curl -fsSL https://app.beta.kaviris.com/cli/install.sh | sh
Linux and macOS. Windows, and downloading by hand: the files are at
https://app.beta.kaviris.com/cli/latest/kaviris-<os>-<arch> (.exe on
Windows) with a SHA256SUMS beside them; see the
quickstart. For your agent, add
this section to AGENTS.md.
Flags every command takes
| Flag | Meaning |
|---|---|
--json |
Print one JSON document on stdout and nothing else there. Progress goes to stderr. For coding agents and scripts |
--app <name or id> |
Which app. Default: the app in .kaviris.json in the project folder |
--dir <path> |
The project folder. Default: the current folder |
--api <url> |
The API. Default https://api.beta.kaviris.com (or KAVIRIS_API) |
Exit codes
| Code | Meaning |
|---|---|
| 0 | Done |
| 1 | Error (the message, or with --json the error and detail, says what) |
| 2 | The deploy was refused, is waiting for approval, or failed |
| 3 | Confirmation needed: repeat the command with --confirm <token> |
Commands
login
Sign in. Opens your browser; --device prints a code to confirm on another
device instead. With --json, the first line is
{"event":"authorize","url":...,"user_code":...} (show it to the user) and
the last document is {"event":"signed_in",...}.
The CLI registers itself with the sign-in server once per machine and keeps
your sign-in in your user's config folder, mode 0600. Access tokens last
10 minutes and are refreshed automatically; after about 10 hours you
sign in again.
--client-id <id> (or KAVIRIS_CLIENT_ID) uses a pre-registered client
instead of registering one.
logout
Forget the stored sign-in.
whoami
Who you are signed in as, your organisations, and what you may do in each.
apps list, apps create <name>, apps get [name], apps delete [name]
List, create, show and delete apps. Names are 1 to 32 characters of a-z,
0-9 and -, and are yours for good once taken.
apps delete shows what will happen and asks you to type the app's id. The
app stops at once and its data is destroyed 30 days later. With --json (or
without a terminal) it prints {"confirmation_required": true, "summary": ..., "confirm_token": ...} and exits with 3; repeat with --confirm <token>
within 5 minutes. --yes skips the question.
deploy
Pack the project folder, upload it, deploy it and follow the deploy to the end.
| Flag | Meaning |
|---|---|
--name <name> |
App name on the first deploy (default: the folder's name) |
--logs |
Show the build log while it runs |
--no-wait |
Start the deploy and return its id at once |
What is uploaded: everything in the folder except what .gitignore and
.kavirisignore exclude (both use the same pattern rules, in any
subfolder), .git, node_modules and .env / .env.* files
(.env.example, .env.sample, .env.template are kept). At most 200 MB
packed.
With --json the result is {"app", "status", "url", "deploy", "next"},
where deploy.refusals is the list described in
Refusals. Entries with severity advise (a
vulnerable library) don't stop the deploy; deploy.upgrades.patch, when
present, is one patch for all the recommended upgrades, to apply with
git apply (vuln_fixable).
The app gets its port in the PORT environment variable; listen on it.
contract show, contract edit, contract approve
show: the contract in force (approved revision), the draft, and what approving the draft would change.edit: change the draft.--patch '<JSON Patch>'applies a patch, such as a refusal'sfix.patch;--patch-file <file>reads it from a file (-for stdin). Without either, your editor opens the draft.approve: put the draft in force.--rev <n>approves the revision you read; by default the current draft. If the change lets the app do more, it asks first (--yesskips that).
secrets set <NAME>, secrets import [file], secrets list
set: send one secret by reference. The value comes from the environment variableNAME(or--from-env VAR), from.env(or--from-dotenv FILE), or from stdin (--stdin). It is never an argument and never printed.import: send every key in a.envfile (default.env).list: names, set or missing, when and by whom. Never values.--declare(set, import): if the contract has no slot for the name, add one and approve it first.
logs
The build log of the app's latest deploy (--deploy <id> for another).
Logs of the running app are coming.
releases, rollback <release>
releases lists earlier releases. rollback goes back to one; it asks
first, like apps delete. Agents do not get rollback or delete rights
automatically.
open
Print the app's address.
version
Print the version.
Environment variables
| Variable | Meaning |
|---|---|
KAVIRIS_API |
API base URL |
KAVIRIS_TOKEN |
Use this access token instead of the stored sign-in (it is not refreshed) |
KAVIRIS_CLIENT_ID |
Pre-registered OAuth client for login |
VISUAL, EDITOR |
Editor for contract edit |