Docs/Getting started/CLI reference

CLI reference

Every openkbs CLI command: login, projects, functions, static sites, storage, Postgres, MQTT, email, custom domains, DNS records, board, images and models.

5 min readUpdated

The openkbs CLI provisions and deploys every elastic service of a project from the terminal: Lambda functions, static sites, storage, Postgres, MQTT, email, custom domains and more. This page lists every command group; the configuration file is covered in the openkbs.json reference.

Installation

bash
curl -fsSL https://openkbs.com/install.sh | bash
openkbs login

Authentication

bash
openkbs login              # Browser-based login (interactive users)
openkbs auth <token>       # Authenticate with project JWT (containers)
openkbs logout             # Clear stored credentials

Projects

bash
openkbs list               # List all projects (alias: ls)
openkbs deploy             # Deploy all elastic services declared in openkbs.json
openkbs update             # Update CLI binary + download latest skill into project

Optional skills

Optional skills are curated add-ons for Claude Code sessions inside a project. Install one only when a task needs it.

bash
openkbs skill list         # Curated optional skills (e.g. ai-act-report, file-transcribe)
openkbs skill add <name>   # Install into .claude/skills — visible to new Claude sessions
openkbs skill rm <name>    # Uninstall

Functions (Lambda)

bash
openkbs fn list            # List deployed functions (alias: ls)
openkbs fn deploy <name>   # Zip ./functions/<name>/ and deploy to Lambda
openkbs fn logs <name>     # Tail recent CloudWatch logs
openkbs fn invoke <name> -d '{"action":"hello"}'   # Invoke: payload = POST event.body (as via URL); prints response body, exit 1 on HTTP ≥400
openkbs fn destroy <name>  # Delete function and its Lambda URL

fn deploy options

  • -s, --schedule <expr> -- Schedule expression, e.g. "rate(1 hour)" or "cron(0 9 * * ? *)"
  • -m, --memory <mb> -- Memory in MB (default from openkbs.json)
  • -t, --timeout <sec> -- Timeout in seconds
  • --no-http -- Disable HTTP access (function URL)
  • -e, --env <KEY=VALUE> -- Custom environment variable (repeatable, e.g. -e API_SECRET=xxx -e DEBUG=true)

Bundle size

Bundle size limit: ~4 MB zipped (the deploy request is capped at 6 MB; a bigger bundle fails with a raw 502/413). @aws-sdk/* v3 is preinstalled in the Lambda runtime — do not put it in dependencies (use devDependencies for local dev). Keep node_modules to what the function actually imports.

Environment variables

Custom environment variables live in a .env file in the function directory:

text
functions/api/.env
env
MY_SECRET=abc123
STRIPE_KEY=sk_live_xxx
NODE_ENV=production

The CLI reads .env on each deploy and injects the variables into the Lambda alongside the auto-injected ones (DATABASE_URL, STORAGE_BUCKET, OPENKBS_PROJECT_ID, OPENKBS_API_KEY). The .env file is gitignored by default (the template .gitignore excludes .*), so secrets never end up in version control.

Env vars can also be passed as CLI flags; these override .env values:

bash
openkbs fn deploy api -e MY_SECRET=abc123 -e DEBUG=true

Static Site

bash
openkbs site deploy        # Deploy ./site/ to S3 + CloudFront; overwrites, removes only old hashed bundles the build replaced
openkbs site prune         # List deployed files no longer in ./site/ (they stay live; delete by name with site rm)
openkbs site rm <path...>  # Delete specific deployed site file(s), e.g. openkbs site rm partner
openkbs site invalidate [paths...]  # Purge CDN cache (no paths = whole site). Deploy already does this; use only if the edge still serves stale content, e.g. openkbs site invalidate /robots.txt /sitemap.xml

Edge redirects, security headers and cache policy for the site are configured in openkbs.json; see Site redirects, Site security headers and Site Cache-Control.

Storage (S3)

bash
openkbs storage list [prefix]              # List objects (alias: ls)
openkbs storage upload <local> [remote]    # Upload a file
openkbs storage download <remote> [local]  # Download a file
openkbs storage rm <keys...>              # Delete objects

PostgreSQL

bash
openkbs postgres info       # Show host, database, engine, status
openkbs postgres connection # Output full connection string
openkbs postgres migrate    # Migrate from Neon to Aurora Serverless v2 (with data)
openkbs postgres migrate --no-data              # Migrate without data (fresh Aurora)
openkbs postgres migrate --min-acu 0.5 --max-acu 8  # Custom scaling
openkbs postgres cleanup-neon  # Delete old Neon DB after verified Aurora migration
openkbs postgres disable --yes # Delete the project database entirely (IRREVERSIBLE — dump first)
openkbs postgres restore --point-in-time "2026-05-13T08:00:00Z"  # Snapshot from point in time
openkbs postgres restore-status           # Check if snapshot is ready (Aurora takes 15-30 min)
openkbs postgres cleanup-restore          # Delete snapshot when done

The three database engines (Neon, Aurora Serverless v2, Postgres Flex) and the point-in-time restore workflow are described in the Elastic services overview.

MQTT (real-time messaging via AWS IoT Core)

bash
openkbs mqtt info                              # Show MQTT status and endpoint
openkbs mqtt enable                            # Enable MQTT for this project
openkbs mqtt disable                           # Disable MQTT
openkbs mqtt token [-u userId]                 # Generate temporary client credentials
openkbs mqtt publish <channel> -d '<json>'     # Publish event to channel

Token scoping, the browser SDK and presence are covered on the MQTT page.

Email

bash
openkbs email enable           # Enable email sending for this project
openkbs email info             # Show email status and usage
openkbs email send <to> -s <subject> -b <body>  # Send email
openkbs email disable          # Disable email
openkbs email verify-domain <domain>  # Verify the project domain for sending (REQUIRED)
openkbs email verify-status           # Check verification status

Email sending requires a custom domain on the project — SES sends only from a verified domain identity. email enable reports active without one, but sending fails until domain add → domain verify → email verify-domain → verify-status. Check openkbs email info for Verified: Yes before building anything that depends on outbound mail (email-code login, password reset, notifications).

Mailboxes, inbox reading and webmail are part of mail hosting; see the Elastic services overview.

Custom Domain

Registering a domain means buying a new name; this is done in the Studio (Cloud tab → Domain → "Register new domain"), is paid in credits, and is not available from the CLI. Parking a domain means connecting a name you already own with domain add; domain check reports availability and price for information only, and the server refuses to park a name that is still available (nobody has bought it yet). Registration and check are apex-only; a subdomain is connected with domain add.

bash
openkbs domain add <domain>    # Park a domain the user already owns (NS at registrar) or a subdomain like app.example.com (one NS record for "app" in the parent DNS; parent site untouched)
openkbs domain check <domain>  # Check availability + registration price (read-only; buying = Studio Cloud tab)
openkbs domain verify          # Check DNS records and certificate status
openkbs domain provision       # Create CloudFront distribution for domain
openkbs domain info            # Show current domain configuration
openkbs domain remove          # Remove custom domain

DNS records

The project's domain lives in a hosted zone managed by OpenKBS. These commands manage the records in that zone:

bash
openkbs domain records                                   # List all records
openkbs domain records set <name> <type> <value...> [--ttl 300]   # Create/replace a record set
openkbs domain records rm <name> <type>                  # Delete a record set
  • <name> is @ for the zone root or a relative name (e.g. www, _dmarc).
  • <type> ∈ A, AAAA, CNAME, TXT, MX, CAA, SRV, NS.
  • Multiple values → one set: openkbs domain records set @ MX "10 mail.x.com" "20 mail2.x.com".

Warning: records set replaces the whole record set for that name and type. Run openkbs domain records first and merge new values into the existing ones — for a TXT/SPF record, keep every existing include: and add the new one (for example include:amazonses.com). A blind overwrite silently drops the other values and breaks mail. Records marked 🔒 managed — the NS/SOA, the TLS certificate-validation CNAMEs and the CloudFront alias records — are platform-owned and the server refuses to edit them. check, info, verify and records (list) are read-only.

Board

The project board is a Trello-like kanban system. openkbs board context returns a compact digest of what is in flight; openkbs board show with filters answers targeted queries without dumping the whole board, which can grow to thousands of cards.

bash
# Orientation — a compact digest, NOT the full board
openkbs board context                  # in-progress + blocked + recent + stale + column counts

# Targeted listing with filters (all optional; archived hidden by default)
openkbs board show --assignee me                       # my active cards
openkbs board show --label urgent --priority high      # urgent & high-priority
openkbs board show --column "In Progress" --stale      # stale in-progress
openkbs board show --blocked                           # cards with open blockers
openkbs board show --q "auth flow"                     # search title + description
openkbs board show --archived                          # include archived too
openkbs board show --json                              # machine-readable for parsing

# Discover what filter values exist (run any of these before filtering)
openkbs board labels                                    # all labels in this project
openkbs board types                                     # all card types
openkbs board columns                                   # all columns
openkbs board members                                   # all project members (valid --assignee)

# Search (title, description, AND comment bodies)
openkbs board search "password reset"

# Card management
openkbs board card <cardId>                         # Read full card detail (description, checklist, comments, activity)
openkbs board edit <cardId>                         # Check out the card description to .openkbs/tmp/card-<id>.md
openkbs board save <cardId>                         # Commit local edits back to the card
openkbs board discard <cardId>                      # Throw away local edits without saving
openkbs board create <title> [-c <column>] [-t <type>] [-p <priority>] [-d <description>]
openkbs board update <cardId> [--title <t>] [--description <d>] [--priority <p>] [--status <s>]
openkbs board move <cardId> <columnName>           # Move card to column by name
openkbs board comment <cardId> <message>           # Add a comment to a card
openkbs board assign <cardId> <email>              # Assign a project member by email (or userId)
openkbs board unassign <cardId> <email>            # Remove an assignee
openkbs board archive <cardId>                     # Hide from default views (reversible)
openkbs board unarchive <cardId>                   # Restore archived card
openkbs board delete <cardId>                       # Permanent delete — only for mistakes/duplicates

# Link cards (blocks, blocked-by, duplicates, duplicated-by, parent-of, child-of, relates-to)
openkbs board link <fromId> <toId> --type <type>   # Create a link between two cards
openkbs board unlink <fromId> <toId> [--type <t>]  # Remove a specific link, or all links between the pair
openkbs board links <cardId>                       # Show all links on a card (outgoing + incoming)

Editing large card descriptions

openkbs board update <id> --description "..." rewrites the entire body, which is expensive for long cards and easy to clobber. For any non-trivial edit use the checkout flow: the description becomes a plain Markdown file that can be edited with normal tools, then saved back.

bash
openkbs board edit 7d5349                  # writes .openkbs/tmp/card-<full-id>.md
# Then use your normal file-editing tools (Edit, Write) on that file to apply
# small, surgical changes — it's a plain markdown file.
openkbs board save 7d5349                  # uploads the new body, deletes the temp file
# or:
openkbs board discard 7d5349               # drop local changes
  • Card types: task, bug, feature, expert-request, spec
  • Priorities: low, medium, high, critical
  • Active vs archived: all cards are active by default; archive hides from views (reversible). Delete is for creation mistakes only.
  • Default columns (new projects): Backlog, In Progress, Review, Done. Projects created before this change keep their original columns.
  • Card IDs: short 8-character strings (e.g. 7d5349Ab) printed by openkbs board. Pass them verbatim to every other command — no truncation, no prefix matching.
  • Comments posted with board comment from the CLI are shown as AI on the board.

Image generation

Generate images with optional reference images for branding, editing and style transfer.

bash
# Generate image
openkbs image "A sunset over mountains" -o site/hero.png

# With reference images
openkbs image "Create a banner with this logo" --ref site/logo.png -o site/banner.png
openkbs image "Product photo in this brand style" --ref brand.png --ref product.jpg -o site/promo.png

# Fast mode (quicker, lighter quality)
openkbs image "Quick sketch" --fast -o site/sketch.png

# Options
openkbs image "Wide banner" --aspect-ratio 16:9 --count 4 -o site/banner.png

Options: -o <file>, --ref <file> (repeatable, up to 10), --aspect-ratio, --count, --fast

Images uploaded in the Studio chat are saved to site/_tmp/ and can be used as --ref paths.

Models

The set of available AI models, their vendors and current pricing are kept in the platform database — there is no hardcoded list. Fetch the live catalog before choosing a model:

bash
openkbs models          # human-readable table
openkbs models --json   # machine-readable (parse this in scripts)

Each entry returns: vendor, model, alias, inputPrice, outputPrice, contextWindow. Prices are in credits per 1K tokens. Programmatic equivalent (same data): GET https://project.openkbs.com/ai/models (public, no auth).

Building something for your company?
We co-build production systems with enterprise teams on this platform.