CLI Reference

Complete reference for the Telbase CLI. Every command, flag, and example.

Installation

bash

npm install -g telbase

The CLI needs Node.js. telbase gcloud also needs the gcloud CLI installed.

Global flags

These flags work with every command:

--json — output as JSON (machine-readable)
--quiet, -q — minimal output
--verbose, -v — debug logging to stderr (works alongside --json)
--service <name> — one service of an app with several, by its name (web, api…); see Full-Stack

Commands that act on one app (db, env, domain, logs, deploys, rollback, the service controls) take --project <app>, or use the current project set with telbase projects switch <name>.

skill

Install or update the Telbase skills where your coding agent reads them, in this directory. See AI Agent Setup.

bash

telbase skill install                  # Claude Code: .claude/skills/
telbase skill install --for cursor     # .cursor/skills/
telbase skill install --for windsurf   # .windsurf/skills/
telbase skill install --for agents-md  # .agents/skills/ and a block in AGENTS.md
telbase skill install --global         # in your home directory, for every project

apps

apps create

bash

telbase apps create my-app --provider vercel --framework nextjs
telbase apps create api --provider cloudrun --database postgres
telbase apps create my-app --service api --provider cloudrun --path /api

--provider <name> — vercel or cloudrun
--database <dialect> — postgres or sqlite: create the app's database
--framework <preset> — the Vercel framework preset, such as nextjs or vite
--root-directory <dir> — the app's folder inside the repository, for a Vercel monorepo
--dir <dir> — the directory the app is deployed from (default: the current one)
--service <name> with --path <path> — add a further service to the registered app, served under its URL at the path (default /<name>); see Full-Stack

The answer gives the app's Telbase URL and its deploy command. telbase apps delete my-app --service api --yes removes one service.

apps list / info

bash

telbase apps list
telbase apps info my-app   # URL, deploy command, database commands, sign-in, services

apps protect

Require sign-in at the app's Telbase URL (every plan).

bash

telbase apps protect my-app --allow [email protected] --allow-domain acme.com
telbase apps protect my-app --sign-in google --session-length 168h
telbase apps protect my-app --off

apps delete

Deletes the app with its hosting, database, files, scheduled jobs and Telbase URL. It cannot be undone.

bash

telbase apps delete my-app --yes

vercel and gcloud

Run the Vercel CLI or gcloud against Telbase's accounts, with your Telbase session. Arguments pass through unchanged. You need no Vercel or Google account.

bash

telbase vercel deploy --prod --yes
telbase gcloud run deploy <service> --source . --region us-central1 --quiet

telbase apps info <app> prints the exact deploy command for each app.

session

Start or refresh the Telbase session (12 hours) that the launchers and telbase db use. They renew it themselves, so you rarely run it.

bash

telbase session

env

Read and write an app's environment variables, which the provider holds. On Vercel a change rebuilds the live deployment.

env set

Set one or more environment variables. Listings mask a value whose key or value looks like a credential.

bash

# Set a variable
telbase env set API_KEY=sk-abc123

# Load from a file
telbase env set --file .env

--file, -f <path> — load variables from a file

env get

Retrieve the value of a specific variable.

bash

telbase env get DATABASE_URL

env list

List all environment variables. Secrets are masked by default.

bash

# List all (secrets masked)
telbase env list

# Reveal all values
telbase env list --show

env unset

Remove an environment variable.

bash

telbase env unset API_KEY

env pull

Download remote variables to a local file.

bash

# Download to .env.local (default)
telbase env pull

# Download to a specific file
telbase env pull --output .env.development

--output, -o <path> — output file (default: .env.local)
--force, -f — overwrite existing file

env push

Upload local variables to the deployed app.

bash

# Push .env.local (default)
telbase env push

# Push a specific file
telbase env push --file .env.production

env diff

Compare local and remote environment variables.

bash

telbase env diff

db

Manage your project's database. See the Databases guide for detailed usage.

db run

Run one command with the app's DATABASE_URL set: migrations, schema tools, seeds. Nothing is written to disk.

bash

telbase db run my-app -- npx prisma migrate deploy
telbase db run my-app -- python manage.py migrate

db status

Show database health, provider, region, and plan.

bash

telbase db status

db info

Show connection details (host, port, user, database).

bash

telbase db info

db connect

Open an interactive psql session (PostgreSQL only).

bash

telbase db connect

db url

Print the database connection string.

bash

telbase db url

db query

Execute a read-only SQL query (SELECT, WITH, EXPLAIN). Max 1,000 rows.

bash

telbase db query "SELECT * FROM users LIMIT 10"
telbase db query --file report.sql

--file, -f <path> — read SQL from a file

db exec

Execute any SQL statement (INSERT, UPDATE, DELETE, CREATE, ALTER).

bash

telbase db exec "CREATE INDEX idx_users_email ON users(email)"
telbase db exec --file migrations/seed.sql

--file, -f <path> — read SQL from a file
--timeout <ms> — timeout in milliseconds (default: 30000, max: 300000)

db create

Create a database manually (normally auto-provisioned on deploy).

bash

telbase db create
telbase db create --name my-database

db delete

Permanently delete the database and all data.

bash

telbase db delete
telbase db delete --force

Destructive action

db delete permanently removes all data. This cannot be undone. Export your data first, for example with pg_dump "$(telbase db url)".

db migrate

Run pending database migrations.

bash

telbase db migrate
telbase db migrate --dry-run

db migrate:status

Show which migrations have been applied and which are pending.

bash

telbase db migrate:status

db migrate:rollback

Guidance for rolling back migrations. Prisma does not support automatic rollback — this command provides manual rollback steps.

bash

telbase db migrate:rollback

db extensions

List available and enabled PostgreSQL extensions.

bash

telbase db extensions

db enable-extension

Enable a PostgreSQL extension.

bash

telbase db enable-extension pgvector
telbase db enable-extension pgvector --preset openai-3-small --create-table

--preset <name> — embedding model preset (openai-ada-002, openai-3-small, openai-3-large, claude, cohere-english, sentence-transformers)
--dimensions <int> — vector dimensions (default: 1536)
--index-type <type> — index type: hnsw, ivfflat, or none (default: hnsw)
--metric <name> — distance metric: cosine, l2, or inner_product (default: cosine)
--create-table — create a sample embeddings table
--table-name <name> — name for the embeddings table (default: embeddings)
--column-name <name> — name for the embedding column (default: embedding)

domain

Manage custom domains with automatic SSL certificates.

domain add

Add a custom domain. Returns DNS instructions.

bash

telbase domain add app.yourcompany.com

The response includes dnsInstructions with the CNAME or A record to add at your DNS provider.

domain remove

Remove a custom domain.

bash

telbase domain remove app.yourcompany.com
telbase domain remove app.yourcompany.com --force

domain list

List all configured domains with verification and SSL status.

bash

telbase domain list

domain verify

Check if DNS records are correctly configured.

bash

telbase domain verify app.yourcompany.com

domain primary

Set the primary (canonical) domain for your app.

bash

telbase domain primary app.yourcompany.com

domain ssl

Check SSL certificate status (issuer, expiration).

bash

telbase domain ssl app.yourcompany.com

Automatic SSL

SSL certificates are provisioned automatically via Let's Encrypt once DNS is verified. No manual certificate management needed.

org

Manage organization-level domains. Organization domains let you serve all projects under your company domain using subdomain or path routing.

org domain add

Add an organization domain with a routing mode.

bash

# Subdomain mode (default): {slug}.acme.com
telbase org domain add acme.com

# Path mode: acme.com/{slug}
telbase org domain add acme.com --mode path

--mode <mode> — routing mode: subdomain (default) or path

Returns DNS instructions (TXT record for verification).

org domain list

List all organization domains with status and routing mode.

bash

telbase org domain list
telbase org domain ls

org domain verify

Verify DNS configuration for an organization domain.

bash

telbase org domain verify acme.com

org domain remove

Remove an organization domain. Projects using it will lose their custom URLs.

bash

telbase org domain remove acme.com
telbase org domain remove acme.com --force

--force — skip confirmation prompt

Plan requirements

Organization domains require Starter ($5/mo) or higher. Free plans cannot add organization domains. Starter and Builder plans allow 1 organization domain. Pro plans allow unlimited.

Subdomain vs path routing

Subdomain mode creates URLs like dashboard.acme.com and api.acme.com. Best for clear project separation. Path mode creates URLs like acme.com/dashboard and acme.com/api. Best for SEO and environments where wildcard DNS is not available. See the Custom Domains guide for details.

projects

List and manage your Telbase projects.

projects (list)

List all projects in your organization.

bash

telbase projects
telbase projects --status running --limit 50

--all, -a — include deleted projects
--limit, -l <int> — max projects to list (default: 20)
--status <name> — filter by status: creating, running, suspended, failed

projects switch

Switch the active project for subsequent commands.

bash

telbase projects switch my-dashboard

projects info

Show detailed project information (framework, provider, last deploy).

bash

telbase projects info
telbase projects info my-dashboard

projects delete

Delete a project. Stops the service, removes env vars and domains. This action is permanent.

bash

telbase projects delete
telbase projects delete my-dashboard --force

auth

Manage authentication with Telbase.

login

Authenticate using device authorization flow. Opens a browser window and displays a confirmation code in your terminal.

bash

telbase login

logout

Clear all stored credentials from this machine.

bash

telbase logout

auth status

Show current authentication status (user, organization, plan, token expiry).

bash

telbase auth status

github

Connect GitHub and link a repository to a project. Telbase does not deploy on push yet: your agent deploys.

github connect

Install the Telbase GitHub App and select repositories.

bash

telbase github connect

github disconnect

Remove the GitHub integration.

bash

telbase github disconnect

github status

Show connected GitHub accounts and linked repos.

bash

telbase github status

github repos

List all GitHub repositories accessible to Telbase.

bash

telbase github repos

github link

Link a GitHub repository to an App: --project <app>, else the current project. unlink, info, autodeploy, branch and deploys take --project too.

bash

telbase github link myorg/my-app --project my-app
telbase github link myorg/my-app --branch develop --no-autodeploy
telbase github link myorg/my-app --root-dir apps/web

--branch <name> — the link's branch (default: main)
--root-dir <path> — root directory within repo (for monorepos)
--no-autodeploy — turn off the link's auto-deploy setting

github unlink

Unlink the repository from the current project.

bash

telbase github unlink

github autodeploy

Turn the link's auto-deploy setting on or off. Telbase does not deploy on push yet, so the setting has no effect until it does.

bash

telbase github autodeploy enable
telbase github autodeploy disable

github branch

Change the link's branch.

bash

telbase github branch develop

github info

Show GitHub link info for the current project.

bash

telbase github info

github deploys

List GitHub-triggered deployments.

bash

telbase github deploys
telbase github deploys --limit 20

--limit <int> — number of deploys to show (default: 10)

storage

Manage file storage (Cloudflare R2). See File Storage for details.

storage create

Create the app's storage bucket. The answer names the bucket and its four values.

bash

telbase storage create my-app
telbase storage create my-app --name my-uploads

--name <name> — custom bucket name

storage status

Show storage status and usage.

bash

telbase storage status my-app

storage credentials

Show, get one value of, or rotate storage credentials.

bash

telbase storage credentials my-app
telbase storage credentials my-app --get R2_SECRET_ACCESS_KEY
telbase storage credentials my-app --rotate --yes

--show — reveal unmasked credentials
--get <name> — print one value alone, to pipe it to the provider
--rotate — rotate access credentials (invalidates old keys immediately)

storage delete

Permanently delete a storage bucket and all its contents.

bash

telbase storage delete my-app --yes
telbase storage delete my-app --force

--yes, -y — skip confirmation; a bucket that holds files is still refused
--force, -f — skip confirmation and delete the files too

storage cors

Manage CORS origins for browser-side uploads.

bash

telbase storage cors list my-app
telbase storage cors add my-app https://my-app.telbase.ai
telbase storage cors remove my-app https://my-app.telbase.ai

storage run

Run one command with the four R2_* values set, for seeds and scripts that write to the bucket.

bash

telbase storage run my-app -- npm run seed

jobs

Scheduled jobs of an app: Cloud Run jobs that Telbase starts on a cron schedule. See Scheduled Jobs.

bash

telbase jobs create my-app nightly-report --schedule "0 6 * * *" --timezone Europe/Paris
telbase jobs list
telbase jobs info nightly-report
telbase jobs run nightly-report
telbase jobs executions nightly-report
telbase jobs pause nightly-report
telbase jobs resume nightly-report
telbase jobs schedule nightly-report --schedule "0 7 * * *"
telbase jobs delete nightly-report --yes

jobs create reserves the job and answers its deploy command, a telbase gcloud run jobs deploy from the directory that holds its code.

team

Manage team members and permissions.

team (list)

List all team members. Runs by default when no subcommand is given.

bash

telbase team

team invite

Invite a new team member by email.

bash

telbase team invite [email protected]
telbase team invite [email protected] --role admin

--role, -r <role> — admin, developer (default), or viewer

team remove

Remove a team member.

bash

telbase team remove [email protected]
telbase team remove [email protected] --force

--force, -f — skip confirmation

team role

Change a member's role.

bash

telbase team role [email protected] admin

access

Manage authentication and access control for deployed applications via Cloudflare Access. Each command acts on --project <app>, else the current project (telbase projects switch).

access enable

Enable SSO authentication. Supported providers: google, microsoft, github, onetimepin.

bash

telbase access enable google
telbase access enable onetimepin

--session <duration> — session length (default: 24h)

access disable

Disable authentication for the project.

bash

telbase access disable
telbase access disable --force

--force, -f — skip confirmation

access domain

Manage allowed email domains.

bash

telbase access domain list
telbase access domain add yourcompany.com
telbase access domain remove yourcompany.com

access allow / deny

Manage individual email allowlist.

bash

telbase access allow [email protected]
telbase access deny [email protected]

access status

Show current authentication configuration.

bash

telbase access status

access users

List who signed in to the app recently, up to 30 days back, each with their latest sign-in.

bash

telbase access users

config

View an App's configuration. It is read-only: the region is set when the App is registered.

config list

List all project configuration settings.

bash

telbase config list

config get

Get a specific configuration value.

bash

telbase config get region --project my-app

services

Control your running service without redeploying.

restart

Gracefully restart your service. Clears memory and restarts background processes.

bash

telbase restart

suspend

Suspend your service to save resources. Configuration, environment variables, and databases are preserved.

bash

telbase suspend
telbase suspend --force

--force, -f — skip confirmation

resume

Resume a previously suspended service.

bash

telbase resume

scale

Scale horizontally (instances) or vertically (plan).

bash

telbase scale --instances 3
telbase scale --plan builder

--instances, -i <int> — number of instances (1-10)
--plan, -p <name> — service plan (free, starter, builder, pro)
--force, -f — skip confirmation for paid upgrades

reset-service

Delete a Cloud Run app's service and create it again from the build that served, with its variables and scaling.

bash

telbase reset-service --project my-app --force

exec

Run a one-off command once in a Cloud Run app's own container, with its variables.

bash

telbase exec --project my-app -- python manage.py createsuperuser --noinput

warm-start

Always On: keep a Cloud Run app's instance warm (a paid feature).

bash

telbase warm-start enable --project my-app
telbase warm-start disable --project my-app

Other Commands

status

Show current deployment status, service health, and resource usage.

bash

telbase status

logs

View application or build logs.

bash

# Recent application logs
telbase logs --project my-app

# Stream live logs
telbase logs --project my-app --follow

# Last 100 lines then exit
telbase logs --lines 100

# Build logs from last deploy
telbase logs --build

# Filter by level
telbase logs --level error

# Logs from a specific time range
telbase logs --since 6h

# Execution history for scheduled jobs
telbase logs --executions

--lines, -n <int> — number of lines to show
--since <duration> — show logs from: 1h, 6h, 24h, 7d, 4w
--search, -s <term> — filter logs containing term
--level, -l <name> — filter by level: info, warn, error
--build — show build logs for last deploy
--deploy <id> — show logs for a specific deploy
--follow, -f — stream live output instead of returning the recent lines
--executions — show execution history for scheduled jobs instead of deploy logs

deploys

List recent deployments with status, trigger, and duration.

bash

telbase deploys
telbase deploys --limit 20

rollback

Serve an earlier live deploy's build again, without rebuilding. It counts as a deploy.

bash

# Rollback to the previous deploy
telbase rollback

# Rollback to a specific deploy
telbase rollback <deploy-id>

# List available rollback targets
telbase rollback --list

# Skip confirmation
telbase rollback --force

cancel

Cancel an in-progress deployment.

bash

telbase cancel
telbase cancel <deploy-id> --force

doctor

Diagnose common issues: sign-in, the Telbase session, the skills in this folder, the Vercel CLI and gcloud, and the app.

bash

telbase doctor
telbase doctor --fix

mcp register

bash

telbase mcp register

mcp unregister

Remove Telbase from Claude Code's MCP configuration.

bash

telbase mcp unregister

open

Open your project in the browser.

bash

telbase open                   # Open deployed app
telbase open --project my-app  # Open another App
telbase open --dashboard       # Open Telbase dashboard
telbase open --logs            # Open logs view
telbase open --github          # Open linked GitHub repo

upgrade

Upgrade the Telbase CLI to the latest version.

bash

telbase upgrade
telbase upgrade --check

--check — check for updates without installing

version

Print version and build information.

bash

telbase version

Need help?

Run telbase --help for a list of all commands, or telbase <command> --help for details on any specific command. For support, email [email protected].