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.

Choose the team

Every command acts on one team. If you belong to more than one, the CLI takes the first of these that is set:

Source	Scope
--team <id-or-slug>	This command
DEPLOYBASE_TEAM	This shell or CI job
.deploybase/project.json	This directory. deploybase link records the team of the project you link
deploybase teams switch <id-or-slug>	Your default on this machine

With none of them set, the API picks the team you used last in the dashboard, else your home team. deploybase whoami shows the team in effect and where it came from.

• A slug is looked up once per command. An unknown slug stops the command before anything is written
• If you are not a member of the chosen team, the command stops with exit code 1 and says where that team came from. It never falls back to another team
• When --team or DEPLOYBASE_TEAM names a different team from the one the directory is linked to, the CLI warns you. The linked project belongs to its own team, so it is not found in the other one
• An API key belongs to one team. With DEPLOYBASE_API_KEY set, --team and DEPLOYBASE_TEAM are ignored with a warning

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
--team <id-or-slug>	Act on this team. See Choose the team

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
DEPLOYBASE_TEAM	none	Team id or slug to act on. --team overrides it; ignored with an API key
NO_COLOR	none	Set to any value to disable coloured output, per no-color.org

Commands

deploybase login

Log in through the OAuth device flow. No flags beyond the global ones.

deploybase login

deploybase logout

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

deploybase logout

deploybase whoami

Show the authenticated user, the team in effect, where that team came from and which authentication method is in use. In --json mode, team_source is flag, env, link, default or server.

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, and its team, automatically. link lists the projects of the team chosen by --team, DEPLOYBASE_TEAM or your default; it ignores the team of an existing link, so you can always relink.

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 teams list

List the teams you belong to with their slug, name, your role, status and id. * marks the team commands act on. Not available with an API key.

deploybase teams list --json

In --json mode each team has id, slug, name, display_label, role, status, is_home and current.

deploybase teams switch

Set the team commands act on by default, on this machine. The default is stored by id in config.json in your user config directory, so renaming the team’s slug does not break it. It does not change the team the dashboard shows.

Flag	Effect
--clear	Remove the default and let the API choose again

deploybase teams switch acme-agency
deploybase teams switch --clear

If DEPLOYBASE_TEAM or a linked directory still takes precedence, the CLI warns you.

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.