CLI Reference

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

Installation

The fastest way to use the CLI is with npx — no install needed:

bash

npx telbase deploy

For a global install:

bash

npm install -g telbase

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> — target a specific service in a multi-service project

deploy

Deploy your app to Telbase. Auto-detects framework, provisions infrastructure, and deploys.

bash

telbase deploy [flags]

Source flags

--local — deploy from local files (default when no --repo)
--repo <url> — deploy from a GitHub repository
--branch <name> — branch to deploy (default: main)
--root-dir <path> — subdirectory for monorepos

Provider flags

--provider <name> — force compute provider: vercel or gcp
--database-provider <name> — force database provider: neon, turso, or cloud_sql
--database — explicitly request database provisioning
--no-db — skip database even if ORM is detected

Build flags

--clear-cache — clear build cache before deploying
--force-env-sync — re-sync all env vars to the provider
--skip-env-check — skip env var detection (useful for CI/CD)

Health check flags

--skip-health-check — skip post-deploy health verification
--health-timeout <seconds> — health check timeout (default: 30)
--health-path <path> — health check endpoint (default: /)

Behavior flags

--auto — skip interactive prompts (required for AI agents and CI/CD)
--no-wait — return immediately without streaming logs

Schedule flags

--schedule <cron> — deploy as a scheduled job with a 5-field cron expression (e.g., "0 * * * *")
--schedule-timezone <tz> — IANA timezone for the schedule (default: UTC)

Examples

bash

# Deploy from current directory
telbase deploy

# Deploy with JSON output (for Claude Code)
telbase deploy --local --json --auto

# Deploy from GitHub
telbase deploy --repo https://github.com/user/my-app

# Force a specific provider
telbase deploy --provider gcp --database-provider cloud_sql

# Monorepo: deploy a subdirectory
telbase deploy --root-dir apps/web

# Deploy without database
telbase deploy --no-db

# Deploy a scheduled job (runs every hour)
telbase deploy --schedule "0 * * * *" --schedule-timezone "America/New_York"

Routing rules

Next.js, Vite (React/Vue/Svelte), Express, Node.js, and static HTML route to Vercel. Docker, Django, FastAPI, Flask, Go, and other Python apps route to GCP Cloud Run. You rarely need to specify providers manually.

run

Manually trigger a scheduled job execution.

bash

telbase run                # Trigger execution
telbase run --follow       # Trigger and stream logs

Flags

--follow, -f — stream execution logs in real-time until completion

env

Manage environment variables and secrets. All values are encrypted at rest.

env set

Set one or more environment variables.

bash

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

# Set a secret (masked in output)
telbase env set DATABASE_URL=postgres://... --secret

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

--file, -f <path> — load variables from a file
--secret, -s — mark all variables as secrets

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 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. Create a backup first with telbase db backup.

db backup

Create a manual backup snapshot.

bash

telbase db backup
telbase db backup --name "before-v2-migration"

db backups

List all available backups (automatic daily + manual).

bash

telbase db backups

db restore

Restore the database from a backup.

bash

telbase db restore <backup-id>
telbase db restore --latest

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 for automatic deployments on every push.

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 the current project for auto-deploy.

bash

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

--branch <name> — branch to deploy from (default: main)
--root-dir <path> — root directory within repo (for monorepos)
--no-autodeploy — disable auto-deploy on push

github unlink

Unlink the repository from the current project.

bash

telbase github unlink

github autodeploy

Enable or disable automatic deployments on push.

bash

telbase github autodeploy enable
telbase github autodeploy disable

github branch

Change the branch that triggers auto-deploy.

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 a new storage bucket.

bash

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

--name <name> — custom bucket name

storage status

Show storage status and usage.

bash

telbase storage status

storage credentials

Show or rotate storage credentials.

bash

telbase storage credentials
telbase storage credentials --show
telbase storage credentials --rotate

--show — reveal unmasked credentials
--rotate — rotate access credentials (invalidates old keys immediately)

storage delete

Permanently delete a storage bucket and all its contents.

bash

telbase storage delete
telbase storage delete --force

--force, -f — skip confirmation

storage cors

Manage CORS origins for browser-side uploads.

bash

telbase storage cors list
telbase storage cors add https://myapp.com
telbase storage cors remove https://myapp.com

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.

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 active authenticated users.

bash

telbase access users

config

View and modify project configuration.

config list

List all project configuration settings.

bash

telbase config list

config get

Get a specific configuration value.

bash

telbase config get region

config set

Set a configuration value. Currently only region is configurable.

bash

telbase config set region us-central1

provider

Manage infrastructure providers. Most operations require platform administrator access.

provider status

Show provider status, health, and which is the default.

bash

telbase provider status

provider set

Set the default compute provider (admin only).

bash

telbase provider set vercel

provider enable / disable

Enable or disable a provider (admin only). Cannot disable the default provider.

bash

telbase provider enable gcp
telbase provider disable gcp

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

Other Commands

init

Initialize a Telbase project in the current directory.

bash

telbase init
telbase init --name my-app --provider vercel

--name <name> — project name (default: directory name)
--force — overwrite existing configuration
--link <name> — link to an existing project by name or ID
--provider <name> — infrastructure provider

status

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

bash

telbase status

logs

View application or build logs.

bash

# Stream application logs
telbase logs

# 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 — follow log output (default: true)
--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

Redeploy a previous successful version.

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 (CLI version, auth, project, service health, database, env vars).

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 --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].