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:
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 |
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/<version>/ 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
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:
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.)
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
PORTenvironment 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 on0.0.0.0. Most frameworks already do. If yours doesn't, the deploy stops with port_mismatch, and your agent can fix it.
In your project folder:
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:
- packs the folder, skipping everything in
.gitignoreand.kavirisignore, plus.git,node_modulesand any.envfile; - uploads it, starts the deploy, and shows the progress;
- 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).
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
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.
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 <token>.
To tell your agent about Kaviris, add the short section in
Instructions for coding agents to your project's AGENTS.md.
The full list is in the CLI reference.