--- title: CLI reference description: Every kaviris command, its flags, its JSON output and exit codes. --- # CLI reference ``` kaviris [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 ```sh 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--` (`.exe` on Windows) with a `SHA256SUMS` beside them; see the [quickstart](../quickstart/cli.md#1-install). For your agent, add [this section](../agents.md) 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 ` | Which app. Default: the app in `.kaviris.json` in the project folder | | `--dir ` | The project folder. Default: the current folder | | `--api ` | 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 ` | ## 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 ` (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 `, `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 ` 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 ` | 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](../concepts/refusals.md). 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](../refusals/vuln_fixable.md)). 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 ''` applies a patch, such as a refusal's `fix.patch`; `--patch-file ` reads it from a file (`-` for stdin). Without either, your editor opens the draft. - `approve`: put the draft in force. `--rev ` approves the revision you read; by default the current draft. If the change lets the app do more, it asks first (`--yes` skips that). ### `secrets set `, `secrets import [file]`, `secrets list` - `set`: send one secret by reference. The value comes from the environment variable `NAME` (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 `.env` file (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 ` for another). Logs of the running app are coming. ### `releases`, `rollback ` `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` |