CLI (ketvia)

The ketvia CLI creates, validates, uploads and debugs Kits. It talks to the developer API with a developer token.

Install

Caution

@ketvia/cli is not published to npm yet. For now, build it from the Ketvia monorepo.

# once it is published
npm i -g @ketvia/cli

# today, from the monorepo
pnpm --filter @ketvia/cli build

Log in

ketvia login
ketvia whoami
ketvia logout

ketvia login takes the developer token from the --token option, the KETVIA_TOKEN environment variable or a prompt. It stores it in ~/.config/ketvia/credentials.json with mode 0600. The directory follows KETVIA_CONFIG_DIR or XDG_CONFIG_HOME when set. ketvia whoami shows the token’s workspace and whether that workspace is your sandbox; ketvia logout removes the stored credentials.

Commands

Command	What it does
ketvia kits create <slug> --template tools|webhook|events	Scaffolds a Kit from a template
ketvia kits validate [--remote]	Checks the manifest; with --remote also against your workspace (ownership, domains, consent difference)
ketvia kits deploy [--publish]	Uploads the manifest as a new version; with --publish also publishes it
ketvia kits publish	Publishes a draft version
ketvia kits logs [--follow --level error --source ...]	Reads the delivery and error log
ketvia kits dev --url <tunnel> [--watch]	Develops in your sandbox over a tunnel

A version is immutable once registered, so deploy of an existing version with a changed manifest fails; bump version first. A new Kit starts private, and a draft is installable only after it is published.

ketvia kits dev

ketvia kits dev --url https://my-tunnel.example.com [--watch]

This command:

1. installs your manifest into your developer sandbox;
2. moves every endpoint URL of the manifest (tools, events, interactivity, commands and OAuth redirects) onto the origin you pass in --url;
3. registers a private version of the sandbox, which is your manifest’s own version, or the next free patch version when the content changed;
4. prints the signing secret once, on the first install. Put it in your server so it can verify Ketvia’s requests.

With --watch the manifest is re-read and re-installed when it changes.

No relay

Ketvia does not run a relay. Ketvia’s servers call your endpoints over the public internet, so your local server must be reachable at a public HTTPS URL that you provide. Use any tunnel you trust, for example ngrok, cloudflared or Tailscale Funnel. The CLI only rewrites URLs; it opens no connection of its own and Ketvia hosts nothing for you.

Worked example

# 1. Start your Kit's server locally
node server.js            # listens on http://localhost:3000

# 2. Expose it with a tunnel you run yourself
cloudflared tunnel --url http://localhost:3000
# prints https://random-words.trycloudflare.com

# 3. Log in with a token created in the sandbox workspace, then install on the tunnel
export KETVIA_TOKEN=kdev_...
ketvia kits dev --url https://random-words.trycloudflare.com --watch

The first run prints the signing secret; set it as the secret your server verifies with verifySignature from the SDK. If the tunnel address changes, run the command again with the new URL.

Output and exit codes

Add --json to any command for machine-readable output.

Exit code	Meaning
0	Success
1	The manifest or the request is invalid
2	Usage or input/output error

Reference

Every call the CLI makes is documented in the developer API reference.