This is a list of keelson CLI commands. You usually do not need to memorize them all because an AI agent runs them through a Skill.
See the Quickstart to install the CLI. Run keelson upgrade to update it.
| Flag | Description |
|---|
--app <slug> | Target app. If omitted, resolved from keelson.yaml in the current directory |
--workspace <slug|name|id> | Target workspace. Required when you belong to multiple workspaces |
--json | Output the result as JSON. Use this from scripts and agents |
--quiet | Output a single line |
--timeout / --retry | Timeout and retry count for API calls |
--no-browser | Display the URL without opening a browser |
When a command fails with --json, it returns {"error":{"code","message","hint","retryable"}} on standard output. Follow hint. If retryable is false, repeating the same command will not change the result.
The former --tenant flag and keelson tenants list command remain accepted
as compatibility aliases. No removal date is set.
| Command | Description |
|---|
keelson login [--no-browser] | Log in through a browser and link this device |
keelson logout [--all-devices] | Delete the saved login credentials on this device and invalidate the server-side session. --all-devices logs out every device |
keelson whoami | Show the current user and workspace |
keelson workspaces list [--query <text>] | List or search the workspaces you belong to |
keelson doctor [--fix-path] | Check PATH, login, and Skill status. --fix-path adds PATH to the shell configuration file |
keelson install-agent <claude-code|codex|cursor> [--global] | Install the Skill for an AI agent. With no argument and --yes, update all installed Skills |
keelson upgrade | Update the CLI to the latest version |
keelson version | Show the version |
keelson telemetry status|off|on | Show, disable, or enable CLI usage telemetry |
| Command | Description |
|---|
keelson deploy | Deploy the app in the current directory and wait for completion |
keelson deploy --new [--secrets-from-env-file <path>] | Create an app and deploy it for the first time. Register values from an env file as secrets and exclude that file from the archive |
keelson deploy --check [--json] | Validate the configuration and display archive contents (excluded files and files that may contain secret values) without uploading |
keelson deploy --ndjson --yes | For scripts. Stream progress as one JSON object per line and finish with {"result":"success"|"failed"} |
keelson status [deploy_id] | Show app or deploy status |
keelson diagnose [deploy_id] | Diagnose a failed deploy (with an ID), including stored startup logs when startup failed, or the running app (without an ID) |
keelson deploys list | Show deploy history |
keelson rollback [deploy_id] | Return to the previous successful deploy, or the specified deploy, without building |
The NDJSON stream may include lines such as
{"stage":"health_check","status":"progress",…} while a stage is running.
Decide success or failure only from the line that contains result.
| Command | Description |
|---|
keelson app curl <path> [-i] [--method] [--data] [--form] [--header] | Send one authenticated request to the app. See Verify a deploy |
keelson preview [--ttl] [--allow-writes] [--json] | Issue a short-lived authenticated ticket |
keelson app info / start / stop / restart | Show app information, start, suspend, or restart the app |
| Command | Description |
|---|
keelson logs app <slug> [--mode live|history] [--severity] [--previous] | Show the app’s standard output and standard error |
keelson logs cron <slug> | Show scheduled job execution logs |
keelson logs access | Show access logs |
keelson logs deploy [deploy_id] [--limit] [--since] | Show deploy progress logs and stored failure details, including startup logs when the app exited during startup. Build output for a successful deploy is not retained, so the command explains when no logs are available |
Pass values through standard input or an env file, not as command arguments.
| Command | Description |
|---|
keelson secrets list | Show configured names and update times |
echo -n "<value>" | keelson secrets set <KEY> [--apply] | Set one value. --apply also redeploys the app |
keelson secrets set --from-env-file <path> [--apply] | Set multiple values from an env file |
keelson secrets unset <KEY> | Delete a secret |
Secrets take effect on the next deploy, or when you use --apply.
| Command | Description |
|---|
keelson apps list | List apps in the workspace |
keelson apps duplicate <slug> --name <new> [--copy-secrets] | Duplicate an app |
keelson apps rename <new_slug> | Change the slug (the URL does not change) |
keelson apps delete [slug] | Delete an app. Browser approval is required |
keelson quotas | Show plan limits and usage |
| Command | Description |
|---|
keelson crons list [--include-disabled] | List jobs |
keelson crons trigger <name> [--wait] | Run a job now |
keelson crons enable <name> / disable <name> | Enable or disable a job |
keelson crons runs list [--cron <name>] | Show execution history |
keelson dev cron run <name> | Run a cron from keelson.yaml locally |
| Command | Description |
|---|
keelson db apply [file.sql] | Run SQL against Managed SQLite. Browser approval is required |
keelson snapshots list | List restore points and in-flight exports |
keelson snapshots create | Create a manual snapshot |
keelson snapshots download <id> -o <file> | Download a backup |
keelson snapshots export --at <RFC3339> | Export data at a specific point in time (PITR) |
keelson snapshots restore <id> | Restore a snapshot. Browser approval is required. The restore can be undone within 72 hours |
keelson snapshots restore-status | Check the progress and result of the latest restore |
keelson db revoke-tokens | Revoke DB authentication tokens (destructive) |
keelson db recover / credential-status | Recover credentials and show their status |
| Command | Description |
|---|
keelson groups list | List groups |
keelson groups create <key> [--name] [--description] [--if-not-exists] | Create a custom group |
keelson groups members list|add|remove <key> <email>... | List, add, or remove members |
keelson access show --app <slug> | Show the app’s view and manage groups |
keelson access set --app <slug> [--view <key>...|--view none] [--manage <key>...] | Set permissions. The manage group list cannot be empty |
| Command | Description |
|---|
keelson apps tokens create --name <n> --scope <api|webhook> [--allowed-ip <cidr>] | Issue an app token (shown only once) |
keelson apps tokens list / rotate / delete | List, rotate, or revoke tokens |
keelson apps directory enable | Issue a Directory API token and register it as KEELSON_DIRECTORY_TOKEN (redeploy required) |
keelson domains add|list|verify|remove <hostname> | Manage custom domains (Team) |
keelson dev email --to ... --subject ... | Send a test inbound email to the local app |
Deleting an app, running SQL, and restoring a snapshot cannot be completed with the CLI alone. The command displays an approval URL and exits with confirmation_required. After you approve the operation in a browser, it runs on the server. You do not need to run the command again. In an interactive terminal, use --wait to wait for completion. Approval expires after 15 minutes.
| Variable | Description |
|---|
KEELSON_TOKEN | Token used instead of login (for CI) |
KEELSON_NO_UPDATE_CHECK / KEELSON_NO_SKILL_SYNC | Disable update checks or automatic Skill updates |
KEELSON_NO_TELEMETRY | Disable CLI usage telemetry |
KEELSON_CONFIG_DIR | Configuration file location |
