CLI

The deploybase CLI is a single Go binary. It drives the same public API the dashboard uses, and it can either trigger a remote build from Git or upload a site you built yourself.

Source: codeberg.org/deploybase/deploybase-cli.

Install

From source, with a Go toolchain:

go install codeberg.org/deploybase/deploybase-cli@latest

Or download a pre-built binary for macOS, Linux or Windows from the releases page, put it on your PATH and make it executable.

Check the install:

deploybase version

Authentication

Interactive login uses the OAuth device flow, so it works over SSH and in containers:

deploybase login

The CLI prints a code and a URL, you approve it in a browser, and the token is written to credentials.json in your user config directory (~/.config/deploybase/ on Linux and macOS) with 0600 permissions. Refresh tokens are used automatically.

For CI and other headless use, set an API key:

export DEPLOYBASE_API_KEY=dbk_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Precedence: DEPLOYBASE_API_KEY wins over a stored login token. With neither, the CLI asks you to log in.

Global flags

These work on every command.

Flag	Effect
`--json`	Print machine-readable JSON instead of human output
`--no-color`	Disable coloured output
`--api-url <url>`	Point the CLI at a different API base URL

Environment variables

Variable	Default	Purpose
`DEPLOYBASE_API_KEY`	none	API key for headless authentication. Takes precedence over a stored login
`DEPLOYBASE_API_URL`	`https://api.deploybase.eu`	API base URL. `--api-url` overrides it
`NO_COLOR`	none	Set to any value to disable coloured output, per no-color.org

Commands

`deploybase login`

deploybase login

`deploybase logout`

Clear the stored credentials. No flags beyond the global ones.

deploybase logout

`deploybase whoami`

Show the authenticated user, the team and which authentication method is in use.

deploybase whoami --json

`deploybase link`

List your projects, let you pick one, and write .deploybase/project.json so later commands in this directory resolve the project automatically.

Flag	Effect
`--project <id-or-slug>`	Link this project without prompting. Required in `--json` mode

deploybase link --project my-site

`deploybase deploy`

deploybase deploy [<dir> | <file.zip>] [flags]

Two modes, chosen by whether you pass an argument.

Git build mode, no argument. Resolves the project, then asks deploybase to clone and build it. Unchanged from earlier releases.

deploybase deploy                    # build the current branch as a preview
deploybase deploy --prod --wait      # build the default branch into production, wait for it

Upload mode, with a directory or a .zip argument. Hashes the files locally, checks them against the limits, uploads them, and publishes the deployment. No clone, no remote build. See deploy a pre-built site for the full walkthrough.

deploybase deploy ./dist
deploybase deploy ./site.zip --preview feat-nav --label "design review"

Flag	Mode	Effect
`--prod`	both	Deploy to production. The default in upload mode
`--branch <name>`	Git build	Branch to build. Defaults to the current Git branch
`--preview <name>`	upload	Deploy as a preview at `{name}-{preview-slug}.previews.deploybase.eu`
`--label <text>`	upload	Free-text label stored with the deployment
`--skip-unchanged`	upload	Compare content with the deployment already serving the target and upload nothing when identical
`--wait`	both	Wait until the deployment reaches a terminal state
`--project <id>`	both	Project ID, overriding auto-detection
`--quiet`	both	Print the URL and nothing else

Auto-detection order for the project: --project, then .deploybase/project.json written by link, then a match of your Git remote URL against your projects.

Flag conflicts

--prod and --preview cannot be combined
--branch with a directory or zip argument is an error: use --preview <name> instead, since no Git branch is involved
--preview, --label and --skip-unchanged only apply in upload mode, and are an error without an argument

Output contract

Human-readable progress, spinners and notes go to standard error
The deployment URL alone goes to standard output, so URL=$(deploybase deploy ./dist) works
--quiet suppresses the progress output and leaves only the URL
--json prints a single object on standard output

The --json object in upload mode:

Field	Type	Meaning
`deployment_id`	string	The deployment that was created, or the existing one when the upload was skipped
`url`	string	The URL the deployment is served from
`files_total`	number	Files in the upload
`files_uploaded`	number	Files actually sent. `0` when the upload was skipped
`bytes_uploaded`	number	Bytes actually sent
`content_hash`	string	Digest of the whole file set, used by `--skip-unchanged`
`skipped_unchanged`	boolean	`true` when nothing was uploaded because the content already matched

`--skip-unchanged`

The CLI builds a content hash from the sorted list of paths and file hashes and compares it with the deployment currently serving the target. On a match it prints that deployment’s URL, exits 0 and never opens an upload session.

With --prod, the comparison is against the project’s live deployment
With --preview <name>, the comparison is best-effort: the CLI looks through the most recent 100 deployed deployments of the project for the newest one with that name. If the match is older than that window, or if the lookup fails, the upload runs normally

`deploybase projects list`

List the projects in your team.

deploybase projects list --json

`deploybase deployments list`

List deployments for the resolved project.

Flag	Default	Effect
`--project <id>`	auto-detected	Project ID, overriding auto-detection
`--limit <n>`	`10`	Maximum number of deployments to show
`--status <status>`	none	Filter by status: `pending`, `queued`, `building`, `deployed`, `failed` or `cancelled`

deploybase deployments list --status deployed --limit 5

`deploybase status`

Show the current project, its latest deployment and the deployment serving production.

Flag	Effect
`--project <id>`	Project ID, overriding auto-detection

deploybase status

`deploybase logs`

deploybase logs [deployment-id]

Show build logs for a deployment, or for the latest deployment when no ID is given.

Flag	Effect
`--project <id>`	Project ID, overriding auto-detection

deploybase logs

`deploybase open`

Open a project URL in your browser. Without flags it opens the production URL.

Flag	Effect
`--preview`	Open the preview URL for the current branch
`--dashboard`	Open the project in the web dashboard
`--project <id>`	Project ID, overriding auto-detection

deploybase open --dashboard

`deploybase version`

Print the CLI version.

deploybase version

Exit codes

Code	Meaning
`0`	Success. In upload mode this includes a run that skipped the upload because nothing changed
`1`	Any error: a failed build, a rejected manifest, an upload that could not complete, or bad flags

Limits

These apply to upload mode and are enforced by the API. The CLI checks the file size and file count locally first, so an oversized site fails before any request is made.

Limit	Value
Size of a single file	25 MiB
Number of files in one upload	20,000
Total size of one upload	250 MiB on the free plan, 1 GiB on paid plans
Upload sessions	60 per hour per team
Lifetime of an upload session	2 hours

Zero-byte files are allowed. .git, node_modules, .DS_Store, __MACOSX, .env and .env.* are never uploaded, and symlinks are rejected rather than followed.