--- title: Quickstart with the command line description: Install the kaviris command, sign in, and deploy a project from your terminal. --- # Quickstart with the command line The `kaviris` command deploys the project in your current folder. Use it in a terminal, in scripts, or from any coding agent that can run commands but has no MCP, or whose MCP sign-in does not work. It is also the most private way to set secrets. ## 1. Install `kaviris` is a single file with no dependencies, for Linux, macOS and Windows on Intel/AMD (`amd64`) and ARM (`arm64`). On Linux or macOS: ```sh curl -fsSL https://app.beta.kaviris.com/cli/install.sh | sh ``` The script picks the build for your machine, checks it against `SHA256SUMS`, and puts it in `/usr/local/bin` if you can write there, otherwise in `~/.local/bin`. It never uses sudo, sends nothing about you, and runs nothing else. Read it first if you like: it is short. If it tells you to add `~/.local/bin` to your `PATH`, do that, then open a new terminal. A terminal or agent session that was already open does not see the change. Or download it yourself from `https://app.beta.kaviris.com/cli/latest/`: | File | For | |---|---| | `kaviris-linux-amd64`, `kaviris-linux-arm64` | Linux | | `kaviris-darwin-arm64`, `kaviris-darwin-amd64` | macOS (Apple silicon, Intel) | | `kaviris-windows-amd64.exe`, `kaviris-windows-arm64.exe` | Windows | | `SHA256SUMS` | the checksum of each file | ```sh curl -fsSLO https://app.beta.kaviris.com/cli/latest/kaviris-linux-amd64 curl -fsSLO https://app.beta.kaviris.com/cli/latest/SHA256SUMS sha256sum -c SHA256SUMS --ignore-missing # macOS: shasum -a 256 -c SHA256SUMS --ignore-missing chmod +x kaviris-linux-amd64 && mv kaviris-linux-amd64 ~/.local/bin/kaviris ``` `latest` always points at the newest version, `/cli//` at one version (`kaviris version` prints yours). Only the newest version is kept for now. The builds are reproducible: `cli/build.sh` at the same commit gives the same `SHA256SUMS`. They are not signed yet. ## 2. Sign in ```sh kaviris login ``` Your browser opens. Create an account with your email address (confirmed with a code we email you) and a passkey (or sign in), and allow the Kaviris CLI access. An agent can run this command, but only you can finish it: the agent shows you the link and waits. On a machine without a browser, such as a server over SSH, use: ```sh kaviris login --device ``` It prints a short code and a link. Open the link on your phone or laptop and confirm the code. This is also the way to sign in from your phone or another device: `kaviris login` without `--device` hands the sign-in straight back to the command, so the browser and the command must be on the same machine. (MCP agents get a page to copy the sign-in from instead; see [Claude Code](claude-code.md#signing-in-from-your-phone-or-another-device).) Your sign-in is stored in your user's config folder (on Linux `~/.config/kaviris/credentials.json`), readable only by you, so it works in every folder. `kaviris logout` removes it. ## 3. Deploy > **One thing to check in your code:** Kaviris tells your app which port to > listen on in the `PORT` environment variable. Read it instead of writing > a port number into the code: `app.listen(process.env.PORT || 3000)` in > Node, `int(os.environ.get("PORT", "8000"))` in Python, and listen on > `0.0.0.0`. Most frameworks already do. If yours doesn't, the deploy > stops with [port_mismatch](../refusals/port_mismatch.md), and your agent > can fix it. In your project folder: ```sh kaviris deploy ``` The first time, this creates an app named after the folder (or use `--name recipes`) and writes `.kaviris.json`, which links the folder to the app. Commit that file. Then it: 1. packs the folder, skipping everything in `.gitignore` and `.kavirisignore`, plus `.git`, `node_modules` and any `.env` file; 2. uploads it, starts the deploy, and shows the progress; 3. prints the address when the app is live, or each problem with its fix. ``` Created app recipes (a-x7k2m9q4w1ab), https://recipes.apps.beta.kaviris.com. Left out .env: secrets are set by reference (kaviris secrets import .env). Uploaded 14 files (38 KB). Deploy d-p3n8c2v6t0yz: building, scanning and checking your app. building checking live Live at https://recipes.apps.beta.kaviris.com ``` Add `--logs` to see the build log as it runs. ## 4. When a deploy is refused Each problem comes with what was found, why it matters, and the exact command that fixes it: ``` REFUSE secret_in_source (server.js:3) What: Stripe secret key is written into the code at server.js:3 Why: anyone with the source or the image can use it; secrets belong in the app's secret slots, set by reference. Fix: Move STRIPE_SECRET_KEY to a secret slot by reference; rotate the key, since it has been in your source. $ kaviris contract edit --patch '[{"op":"add","path":"/secretSlots","value":["STRIPE_SECRET_KEY"]}]' $ kaviris contract approve $ kaviris secrets set STRIPE_SECRET_KEY --from-env STRIPE_SECRET_KEY Docs: https://docs.beta.kaviris.com/refusals/secret_in_source ``` Recommendations, such as an upgrade for a library with a known security hole, are printed too, but the deploy goes live anyway. With `--json`, `deploy.upgrades.patch` is a ready-made patch for all of them: save it and run `git apply` ([details](../refusals/vuln_fixable.md)). Fix it and run `kaviris deploy` again. If the deploy is only waiting for your approval (a new outside service, say), apply the patch and run `kaviris contract approve`: the waiting deploy then continues by itself. ## 5. Secrets ```sh kaviris secrets import .env # every key in .env kaviris secrets set OPENAI_API_KEY # from your environment, or from .env kaviris secrets list # names and when they were set, never values ``` Add `--declare` the first time, to add the secret to your app's contract. See [Secrets](../concepts/secrets.md). ## For coding agents Every command takes `--json` and then prints exactly one JSON document on standard output, and progress on standard error. Exit codes: `0` done, `1` error, `2` deploy refused, waiting for approval or failed, `3` confirmation needed. Destructive commands (`apps delete`, `rollback`) first print a summary and a `confirm_token`; show the summary to the user, and only if they agree, repeat the command with `--confirm `. To tell your agent about Kaviris, add the short section in [Instructions for coding agents](../agents.md) to your project's `AGENTS.md`. The full list is in the [CLI reference](../reference/cli.md).