CLI documentation

#Overview

Klonna tars your AI agent's state — .claude/, CLAUDE.md, .mcp.json, AGENTS.md — encrypts the archive on your machine, and uploads only the ciphertext. Restore it on any machine the CLI runs on.

Encryption is zero-knowledge. Every backup is sealed with AES-256-GCM using a key derived from your passphrase via scrypt. Both the passphrase and the plaintext never leave your machine; the server only ever stores bytes it cannot read.

Zero-knowledge cuts both ways: there is no passphrase reset and no recovery path. If you lose the passphrase, every backup encrypted with it is unrecoverable — by design. Store it in a password manager.

#Install

Prerequisite: Node.js >= 20.17. Check with node --version. Then install globally from npm:

$ npm i -g @klonna/cli

The package installs a single binary, klonna — the command used throughout these docs.

#Authenticate

Sign in once per machine with klonna login. It opens the CLI sign-in page in your browser (and prints the URL as a fallback). Sign in there, click Reveal, copy the one-time session code, and paste it back into the terminal prompt.

$ klonna login

On success the CLI prints Logged in as <email> and stores your session in ~/.klonna/config.json. Verify any time by running klonna list — it exits cleanly when you are signed in. An expired session prints Session expired — run `klonna login`; just run login again.

API keys (CI & AI agents)

For non-interactive environments — CI pipelines and AI agents that cannot run a browser — authenticate with a long-lived API key instead. Create one in the dashboard under Account → API keys (it is shown once and is revocable there at any time). Then set it in the environment — no browser and no config file needed:

$ export KLONNA_API_KEY="klo_…"

With KLONNA_API_KEY set, every command authenticates with that key (it takes precedence over any saved login). You can also run klonna login --api-key <key> to validate a key and save it to your config. Keep the key out of version control, logs, and shell history — treat it like the passphrase.

#Commands reference

Every command exits 0 on success and 1 on error. The <id> for restore and delete is the full backup UUID or any unique prefix of it — the 8-character short IDs that klonna list prints work.

klonna init

Detect agent state in this directory and create .klonnarc.json.

Run from your project root. A .claude/ directory is detected as a claude-code project; otherwise an AGENTS.md file is detected as a generic project; if neither is present the command exits with guidance.

It writes a .klonnarc.json manifest with the include patterns, the hard-coded exclude list, and the per-file size cap, then prints the detected agent type so you can review what will be backed up.

An existing .klonnarc.json is never overwritten — the command says so and exits cleanly. Edit the file directly, or delete it and re-run.

Example

$ klonna init

klonna save

klonna save [options]

Archive, encrypt, and upload this project's agent state.

Selects files per .klonnarc.json, tars them, encrypts the archive locally with AES-256-GCM, and uploads only the ciphertext. Every save creates a new, independent backup — saves never overwrite earlier ones.

You are prompted for the encryption passphrase (masked). The very first save on a machine asks twice and shows the zero-knowledge warning; later saves ask once. Set KLONNA_PASSPHRASE in the environment to supply it non-interactively (for CI) and skip the double-confirm. The passphrase is never accepted as a command-line argument.

Files matching the secret patterns are never uploaded and are listed in the output. Files over the 50 MiB (52.4 MB) per-file cap are skipped and listed too — both summaries are printed so nothing is withheld silently.

On success it prints the backup ID, the encrypted size, and the creation timestamp.

-n, --note <text>: attach a note to this backup (max 500 chars)
-w, --workspace <id-or-name>: save into this workspace (default: personal)
--no-manifest: do not attach the file manifest to this backup

Example

$ KLONNA_PASSPHRASE="<passphrase>" klonna save --note "my-project: first backup"

klonna list

klonna list [options]

List your backups in a table.

Prints a table with the columns ID, AGENT, SIZE, CREATED, and NOTE, where ID is the first 8 characters of each backup’s UUID. Those short IDs are what restore and delete accept.

There is no project or path column, so the note is the only way to tell backups apart later — start each note with the project name.

With no backups it prints "No backups yet — run `klonna save` to create one." and still exits 0. Running list is also the quickest way to confirm you are logged in.

-w, --workspace <id-or-name>: list this workspace's backups (default: personal)

Example

$ klonna list

klonna restore

klonna restore [options] <id> [dir]

Download, decrypt, and extract a backup into a directory.

The id is the full UUID or any unique prefix of it — the 8-character short IDs from klonna list work. The destination dir defaults to the current directory (".").

The destination must be empty (or not yet exist) unless you pass --force; this check runs before any network call. --force allows overwriting files that exist in the backup but never deletes files that are only in the destination. Prefer an empty or new directory.

You are prompted for the passphrase (or set KLONNA_PASSPHRASE). The archive is downloaded, the AES-GCM authentication tag is verified, and only then is anything extracted — a wrong passphrase extracts nothing.

--force: allow overwriting files in a non-empty directory (never deletes)
-w, --workspace <id-or-name>: workspace searched when resolving a short id (default: personal)

Example

$ KLONNA_PASSPHRASE="<passphrase>" klonna restore 3f9c2a1e ~/restored-project

klonna delete

klonna delete [options] <id>

Delete a backup permanently.

Deletes both the database row and the stored object. Deletion is permanent and frees the workspace’s quota immediately.

Without --yes the command asks for interactive confirmation ("Delete backup <id>? This cannot be undone."). Pass --yes (alias -y) to skip the prompt in scripts.

The id accepts the same full-UUID-or-short-prefix form as restore.

-y, --yes: skip the confirmation prompt
-w, --workspace <id-or-name>: workspace searched when resolving a short id (default: personal)

Example

$ klonna delete 3f9c2a1e --yes

klonna workspaces

List the workspaces you belong to.

Prints a table of the workspaces you can access — short ID, name, your role, and a PERSONAL marker for your personal workspace. Your personal workspace is listed first.

Use the ID or exact name with the -w/--workspace flag on save, list, restore, and delete to target a shared workspace. The CLI can read and target workspaces but cannot create them or manage members — that is done in the web dashboard.

Example

$ klonna workspaces

#Workspaces & sharing

Every backup belongs to exactly one workspace. With no --workspace flag, save, list, restore, and delete all operate on your personal workspace — one per account, private to you.

Shared workspaces let teammates see and restore the same backups. Target one with -w, --workspace <id-or-name> on any of those commands; the value is a workspace's full UUID, a unique short-id prefix, or its exact name. Run klonna workspaces to see the ones you can access.

Creating workspaces and inviting or removing members is done in the web dashboard — the CLI can read and target workspaces but cannot manage membership. Manage members from the Workspaces dashboard. To join a workspace you were invited to, open the invite link and accept it in the browser; afterward it appears in klonna workspaces.

Quota is charged against the workspace owner's plan, not yours — so saving into a Pro owner's shared workspace uses that owner's limits.

#Manifests

Each klonna save also stores a manifest: the list of file paths and their byte sizes inside the archive — names and sizes only, never contents. The web dashboard renders it as a browsable file tree so you can confirm what a backup contains without decrypting it.

This does not weaken the zero-knowledge guarantee — the archive bytes stay encrypted and the server still cannot read any file. Pass --no-manifest to klonna save to skip storing the index (for example when the path names themselves are sensitive); the backup still restores normally, and klonna restore never needs the manifest.

#Configuration

Your session lives in ~/.klonna/config.json, written with 0600 permissions (the directory is 0700). The CLI rotates its refresh token on every command, so you stay signed in without re-running login.

In normal use the CLI needs no environment variables — production URLs are compiled in. These overrides exist for CI and local development:

KLONNA_API_KEY: A long-lived API key (klo_…) used as the bearer credential for every request — the non-interactive auth path for CI and AI agents, no browser or config file needed. Takes precedence over any saved login. Create one in the dashboard (Account → API keys); it is shown once and revocable there.
KLONNA_PASSPHRASE: Non-interactive encryption passphrase for save and restore (e.g. CI). Never passed as a command-line argument.
KLONNA_API_URL: Base URL of the web app / API (e.g. http://localhost:3000). For local development.
KLONNA_SUPABASE_URL: Supabase project URL override.
KLONNA_SUPABASE_ANON_KEY: Supabase anon / publishable key override.
KLONNA_CONFIG_DIR: Directory holding CLI session state (default ~/.klonna). Useful for sharing a login across containers or CI.

File selection lives in your project's .klonnarc.json (include, exclude, maxFileSizeBytes). These secret patterns are always excluded in code even if you empty that list: .env* *.pem *.key id_rsa* id_ed25519* .aws/** .ssh/** credentials.json .netrc *.tfstate. The per-file cap defaults to 50 MiB (52.4 MB).

#For AI agents

Driving this CLI from an AI coding agent? There is a dedicated, machine-readable operating guide that covers the non-interactive paths (non-interactive auth via the KLONNA_API_KEY env var, the KLONNA_PASSPHRASE env var, --yes for delete), browser login as the human fallback, and an error → action table.

Read the agent guide →