kivel command line interface
Use the kivel CLI to run utilities from a pipe, create webhook inboxes, upload and download files, and call any /api/ endpoint with JSON output.
Updated 30 October 2026What the CLI is for
kivel is a small command line client for shell scripts and CI. It reads input from standard input, prints JSON to standard output, writes errors as JSON to standard error and exits with a nonzero code on failure. It is built on the TypeScript SDK.
The CLI beta is published as @kivel.io/cli. Install it with npm install --global @kivel.io/cli@beta, or run npx [email protected]/cli@beta kivel --help. It installs the matching SDK automatically. In the repository you can also use pnpm cli instead of kivel.
Configure
The CLI reads three environment variables. Without an API key it works anonymously.
| Variable | Purpose |
|---|---|
| KIVEL_URL | API origin; defaults to https://kivel.io |
| KIVEL_API_KEY | Workspace API key sent as a Bearer token |
| KIVEL_ACCESS_TOKEN | Access token used by download when --access-token is not given |
Commands
Webhook, mock and file creation accepts --ttl-seconds and --persistent. Email uses --active-days (1–7, default 3) and an optional paid --local-part. Webhooks, mocks, mock MCP servers and files default to private visibility. Email addresses accept incoming mail publicly; reading mail always requires management access. Agent login/trial commands use their own fixed expiry rules.
| Command | What it does |
|---|---|
| kivel tools | List tools (GET /api/tools) |
| kivel describe <tool-id> | Show one tool and its options |
| kivel usage | Show your plan, limits and runs today |
| kivel resources | List workspace resources (needs an API key) |
| kivel agent login <name> / agent token | Start device login, then pipe {"deviceCode":"…"} to agent token after browser approval; save the returned key privately |
| kivel agent trial <name> | Start a 72-hour anonymous-limit trial; --human-email optionally notifies the human |
| kivel credential save / list / inspect / reveal | Save from JSON stdin, read metadata, then reveal with an approved --approval-id |
| kivel email create / messages <id> / wait <id> | Owned mail; email list reopens addresses and email forward reads a webhook URL from stdin; waits accept --after and --timeout-seconds |
| kivel email threads / thread / draft-create / draft-submit | Read conversations, save a draft from JSON, then send or request approval with an optional sendAt |
| kivel memory set|get|delete <namespace> <key> | Pipe a JSON value to set; memory list <namespace> accepts --prefix |
| kivel monitor create|list|inspect|pause|resume|delete [id] | Pipe monitor settings as JSON to create |
| kivel monitor ping|fail <ping-token> | Report job success or failure using the secret from pingUrl |
| kivel approval ask|list|pending|inspect|wait [id] | Pipe question/options as JSON to ask; only the signed-in human can answer |
| kivel inbox requests|wait|response|forward|deliveries <id> | Read requests, wait, pipe response/forward settings as JSON, or inspect delivery attempts |
| kivel mock create|update|calls|reset [id] | Pipe mock configuration as JSON to create/update |
| kivel mcp-server create | Pipe a mock MCP configuration as JSON |
| kivel inbox|email|mock|mcp-server|file inspect|delete|renew <id> | Shared lifecycle commands; --token for anonymous management, --persistent on renew for paid leases |
| kivel run <tool-id> [--options JSON] [--file <name>] | Run a utility with standard input as text, or as file bytes with --file |
| kivel inbox create [--visibility private|public] | Create a webhook inbox |
| kivel upload <filename> [--visibility ...] [--max-downloads n] | Upload standard input as a file |
| kivel download <file-id> [--access-token token] | Write file bytes to standard output |
| kivel api <METHOD> /api/path [--token <resource-token>] | Call any /api/ endpoint with standard input as the JSON body |
export KIVEL_API_KEY='kv_...'
printf '{"hello":true}' | kivel run json --options '{"action":"minify"}'
kivel run everyday-file-checksums --file report.pdf < report.pdf
kivel inbox create
kivel upload report.txt --max-downloads 1 < report.txt
kivel download FILE_ID --access-token "$ACCESS_TOKEN" > report.txt
kivel api GET /api/inboxes/INBOX_ID/requests --token "$INSPECTION_TOKEN"
kivel api DELETE /api/mocks/MOCK_ID --token "$MANAGEMENT_TOKEN"Output and errors
- Results print as indented JSON; download prints raw bytes; help prints plain text.
- Errors print {"error", "status", "requestId", "retryAfter"} to standard error and exit with code 1.
- Standard input is limited to 10 MiB. Requests time out after 90 seconds.
- Mutations are never retried automatically.
- The api command accepts GET, HEAD, OPTIONS, POST, PUT, PATCH and DELETE. It sends --token in X-Resource-Token for /api/ paths, or X-Access-Token for /mock/ callers, alongside any workspace key.
Frequently asked questions
How do I install the kivel CLI?
Install npm install --global @kivel.io/cli@beta, or use npx [email protected]/cli@beta kivel --help without a global installation. The CLI requires Node.js 22.13+. Use the scoped package name @kivel.io/cli; the executable is named kivel.
How do I run a multi-file tool such as PDF merging from the CLI?
Use the api command: pipe a JSON body with a file array to kivel api POST /api/tools/everyday-merge-pdfs/run.
How do I point the CLI at a self-hosted installation?
Set KIVEL_URL to its origin. Remote origins must use HTTPS; plain HTTP is allowed only for localhost.