CLI overview

Authenticate, analyze monorepos, bulk-import, deploy --all, manage deployment environments, sync Variables, stream logs, and open databases.

The Bytstack CLI (@bytstack/cli) mirrors common dashboard actions for local workflows and CI.

Install

npm i -g @bytstack/cli

pnpm add -g @bytstack/cli

yarn global add @bytstack/cli

Authenticate

bytstack login
# or non-interactive:
bytstack login --token <token> --api-url https://api.example.com

Flag	Purpose
`--token <token>`	API token (skip browser OAuth)
`--no-browser`	Prompt for a token instead of opening a browser
`--api-url <url>`	API base URL

API URL resolution (highest wins): .bytstack/config.json apiUrl → BYTSTACK_API_URL → http://localhost:3000.

Token resolution: BYTSTACK_TOKEN → ~/.bytstack/credentials.json.

Link a project directory

bytstack link <serviceId> [--project-id <id>] [--api-url <url>]
bytstack link --project <projectId>    # enough for deploy --all / env groups
bytstack link --project proj_<id> --environment staging

Writes .bytstack/config.json with serviceId and/or projectId (and optional environmentId). Most commands also accept --service / --project / --environment so CI does not need a local link file.

Happy path — monorepo

bytstack analyze --repo acme/app
bytstack import --all --repo acme/app --project-name my-stack --yes
bytstack deploy --all --watch

Flag-gated APIs (workspace_orchestrator, env_groups, deployment_environments) return feature_disabled until enabled by a platform admin. See Monorepos.

Happy path — deployment environments

Requires the deployment_environments platform flag (or dogfood allowlist).

bytstack link --project proj_<id>
bytstack environment list
bytstack environment duplicate --from production --name Staging --slug staging --branch staging --yes
bytstack environment select staging
bytstack env pull --scope project --file .env.staging
# edit secrets, then:
bytstack env push --scope project --file .env.staging --overwrite --yes
bytstack deploy --all --watch
# after soak:
bytstack environment promote staging --to production --yes --watch

environment select writes environmentId into .bytstack/config.json. deploy --all and project-scoped env commands use that selection (or --environment); if neither is set they default to production and print a stderr notice.

bytstack env promote still means Share to project (variable scope). Stage promotion is only bytstack environment promote. Guide: Deployment environments.

Commands

Command	Purpose
`bytstack login`	Browser OAuth or token auth
`bytstack link`	Link cwd to a service and/or project (+ optional environment)
`bytstack analyze`	Detect monorepo services + DB offers
`bytstack import --all`	Bulk-create selected services (+ optional Postgres)
`bytstack environment list \| select \| duplicate \| promote`	Deployment stages
`bytstack deploy`	Queue a deployment (linked service)
`bytstack deploy --all`	Deploy every non-preview service in the selected environment
`bytstack deploy --service <name\|id>`	Deploy one service by name or id
`bytstack logs`	Build or runtime logs
`bytstack env list \| set \| pull \| push`	Sync Variables (project/service)
`bytstack env groups …`	List / create / attach / detach / set group vars
`bytstack db connection <id>`	Print external DB URL
`bytstack db psql <id>`	Open `psql` on the external URL
`bytstack open`	Open the service platform URL

Analyze & import

bytstack analyze --repo acme/app
bytstack analyze --repo acme/app --ref main --json
bytstack import --all --repo acme/app --project-name my-stack --yes
bytstack import --all --repo acme/app --project proj_<id> --yes
bytstack analyze --repo acme/app --json | bytstack import --all --from-file - --repo acme/app --project-name x --yes

--yes skips confirmation for non-interactive CI. Quota overruns return 402 with zero rows created.

Deploy

bytstack deploy                        # linked service
bytstack deploy --service api
bytstack deploy --all --watch
bytstack deploy --all --environment staging
bytstack deploy --watch --timeout 900  # default 15m; 0 waits indefinitely
bytstack deploy --watch --json         # final JSON only (CI)

Outcome	Exit code
live	0
failed	1
timeout	2
Ctrl+C (deploy keeps running)	130

Logs

bytstack logs                 # runtime (default)
bytstack logs --build         # latest deployment build logs
bytstack logs --follow        # keep tailing
bytstack logs --since 1h --query error

Useful flags: --build, --tail, --since, --query / --search, --deployment, --historical, --download, --no-wake, -f / --follow.

Deployment environments

bytstack environment list
bytstack environment select staging
bytstack environment duplicate --from production --name Staging --slug staging --yes
bytstack environment promote staging --to production --dry-run
bytstack environment promote staging --to production --yes --watch

Details: Deployment environments.

Variables (`bytstack env`)

Project-scoped commands use the selected deployment environment from bytstack environment select or --environment. Service-scoped commands target the linked service instance (already env-specific).

bytstack env list
bytstack env list --scope project --environment staging --json
bytstack env set DATABASE_POOL_SIZE=20
bytstack env pull --scope project --file .env.staging
bytstack env push --scope project --overwrite --yes
bytstack env promote KEY                 # Share to project (not stage Promote)

Env groups

bytstack env groups list
bytstack env groups create backend --description "API secrets"
bytstack env groups set backend STRIPE_KEY=sk_…
bytstack env groups attach backend api
bytstack env groups detach backend api

Requires the env_groups platform flag. Details: Variables — env groups.

Databases

bytstack db connection <databaseId>
bytstack db psql <databaseId>

External URLs are TLS-terminated and subject to allowlists configured in the dashboard.

Redis

bytstack redis create --name cache --preset cache
bytstack redis list
bytstack redis url <id>
bytstack redis rotate <id> --yes
bytstack redis cli <id> --ping
bytstack redis backups <id> --create
bytstack redis ha enable <id>

Quick connect snippets in bytstack redis --help match the dashboard. Details: Managed Redis.

CI

Create an API token in the dashboard.
Set BYTSTACK_TOKEN and BYTSTACK_API_URL in the pipeline.
Commit or generate .bytstack/config.json with projectId (and serviceId / environmentId when needed).
Run bytstack deploy --all --watch --json (or a single deploy --watch) and fail the job unless the deployment reaches live.

On this page