Command reference
This page defines the implemented v0.1.9 command surface. Dopbase does not infer a project or environment from the current directory. Management commands receive an environment reference directly. run may use a server-scoped default from the user configuration.
For a compact table of every command, command-specific option, and example, see the CLI cheat sheet.
Connections and authentication
When no server is configured, client commands use http://localhost:8840. client connect validates a new endpoint, asks for interactive confirmation, stops the current managed background server when present, deletes the previous encrypted CLI session, clears the saved default environment, and then saves the new endpoint. A foreground server must first be stopped with Ctrl+C. It does not select a project or environment, stop remote or unrelated local servers, or revoke browser sessions.
Server setup
Use dopbase server setup for optional standalone terminal initialization. It prompts for the root email, a masked password of 12 to 128 characters, and confirmation when no email default is supplied. --email EMAIL or DOPBASE_ROOT_EMAIL generates a password and prints it once without prompting; this mode also supports global --json. Explicit --email takes precedence.
Setup accepts --config and --master-key-file with global --data-dir, rejects --server, and leaves the server stopped. It creates no client session and does not change the selected client endpoint. dopbase init remains the project and environment workflow.
server setup --web starts the existing foreground web flow, including backup restore. It accepts the foreground listener options listed below, continues serving after setup, and stops with Ctrl+C. --email or DOPBASE_ROOT_EMAIL prefills the email through the printed setup link. Web setup rejects --json. Listener options require --web when used with setup. See server setup for output, recovery, and instance selection.
Server lifecycle
Fresh startup enters existing web setup, or creates root with a generated password when DOPBASE_ROOT_EMAIL is supplied. Existing instances preserve credentials. With the web UI disabled and no email, complete CLI setup first. Interrupted factory resets also require explicit setup. server start stays attached to the terminal and stops with Ctrl+C. On macOS and Linux, server start --background starts a managed background process. Use server stop to stop it, server status to inspect it, and server logs to read its output. server restart restarts a running background server with its saved CLI and environment overrides while rereading configuration. It accepts --timeout (default 10 seconds). Stop and start again to change explicit launch overrides. See server lifecycle for options, migration steps, and examples.
server start accepts these options in either mode:
server stop --timeout <SECONDS> waits 10 seconds by default. server logs accepts --lines <COUNT> (default 100), --watch or -w, and --clean. --clean --watch clears the existing log before waiting for new output.
server up and server down have been replaced by server start --background and server stop. The old commands show an informational migration notice and exit with status 1 without starting or stopping a server.
The old top-level serve, serve --background, and stop commands are not supported. Use server start, server start --background, and server stop respectively.
Check for updates
dopbase update compares the running version against the latest release tag on GitHub. It is informational only and never modifies the binary:
dopbase 0.1.9 is up to date (latest release 0.1.9).When a newer release exists, the command prints the current version, the latest version, and the release URL. Stop every running Dopbase server, then install the release with:
curl -fsSL https://dopbase.com/install.sh | shThe command exits with status 0 whether or not an update is available, and with status 1 when the release cannot be queried. Run it with --json for automation. No other command contacts GitHub.
The server resolution order is:
- A global
--server <url>argument DOPBASE_URL- The endpoint saved by
dopbase client connect http://localhost:8840
Machine runners can save an encrypted credential with dopbase login --token. CI systems and deployment platforms should inject DOPBASE_TOKEN from their secret store. Authentication uses DOPBASE_TOKEN, then the encrypted credential saved by login. A saved credential is used only when it matches the resolved server. An invalid environment credential never falls back to the saved one.
dopbase client status displays the config path, resolved server and its source, authentication source, locally identified credential type, login email, and the saved default environment. It performs a short health check and reports connected (live) or offline (cache) without failing when the server is unavailable. It never displays token contents. See client configuration for the TOML schema and override behavior.
Environment references
Every environment belongs to one project, so an environment reference contains all the context needed by secret, import, export, token, and run commands.
Commands accept these forms:
env_482731 # Immutable environment ID
payment-service/production # Project name and environment name
prj_01JABCDEF1234/production # Project ID and environment nameUse readable references interactively. Use immutable IDs in CI and deployment configuration because an environment ID does not change when its project or environment is renamed.
Project names are unique within one Dopbase server. Environment names are unique within their project. IDs belong to the Dopbase server that created them. An ID from one server cannot address a resource on another server.
Bootstrap a project
init creates a project, its first environment, and its secrets in one operation:
dopbase init
dopbase init payment-service/development --from .env
dopbase init worker/development --from secrets.json
cat secrets.yml | dopbase init storefront/development --from - --format yamlRun dopbase init without arguments from a directory that contains .env. The CLI checks the server and login, shows the number of variables it found, and asks for a new project/environment target. A key-name check estimates how many variables may be sensitive without using or printing their values. All variables are imported.
After a successful interactive import, Dopbase asks whether to delete .env. Yes is selected by default. The file is kept if it changed after Dopbase read it, and the command never edits .gitignore.
Use the explicit form for scripts, stdin, JSON, YAML, TOML, or machine-readable output. Both modes validate the complete file before changing server state. The project, environment, and secrets are created atomically, so a failed request cannot leave a partial project. Terminal output never includes secret values.
Project commands
<PROJECT_REF> accepts an immutable project ID or project name. Deleting a project also deletes its environments, secrets, and scoped tokens. Dopbase shows the affected resource counts and requires confirmation. Automation must pass --yes.
Environment commands
dopbase env list shows ENVIRONMENT, ID, and UPDATED columns. Each ENVIRONMENT value uses the project and environment names, such as payment-service/local. Filtering by project name or ID keeps this format. --json returns the environment records with separate projectName and name fields.
ENVIRONMENT ID UPDATED
payment-service/local env_100001 2026-10-05 08:30 UTC
payment-service/production env_100002 2026-10-05 09:00 UTC
2 environment(s)Deleting an environment also deletes its secrets and scoped tokens. The operation requires confirmation or --yes and is recorded in the audit log.
Clone an environment when a local, preview, or production environment should start with the same secrets as an existing environment:
dopbase env clone payment-service/local production
dopbase env clone storefront/staging preview-42 --yesThe source must use PROJECT_REF/ENVIRONMENT_NAME. The new environment is created in that project, so cloning across projects or servers is not supported. Dopbase resolves the source, checks that the new name is available, shows the source, destination, and secret count, then asks for confirmation. --yes skips this confirmation but still requires a recently authenticated human account. Runner tokens and service accounts cannot clone environments.
Dopbase creates the destination before reading plaintext secrets. This closes a name-conflict race without exposing source values. If export or import fails, the CLI tries to remove the new environment and reports whether cleanup succeeded. Secret values remain in memory and are not written to a temporary file.
A successful clone prints every environment in the project. With --json, it returns the same environment array as dopbase env list <PROJECT_REF> --json. The clone copies current secret key/value pairs only. It does not copy editor layout, tokens, audit history, IDs, or timestamps, and it does not keep the two environments synchronized.
Edit a whole environment
dopbase env edit payment-service/staging
dopbase env edit payment-service/staging --editor hx
dopbase env edit payment-service/staging --editor nvim --dry-runenv edit requires a terminal. With an existing login, Dopbase first checks that the environment exists and lists its secret metadata. If it is empty, Dopbase asks whether to add secrets; pressing Enter exits without password confirmation or opening an editor. Existing sessions always require password confirmation before export. A login completed by this command counts as confirmation, so it does not ask twice.
Editor selection uses --editor, then VISUAL, then EDITOR. If none is set, Dopbase checks for nvim, vim, hx, and nano, in that order. Commands are split into arguments without a shell; shell expansion and pipelines are unavailable.
The editor opens the current secrets as .env text. On exit, Dopbase parses the document and runs a server dry run. The preview lists added, updated, and deleted key names without showing their values. Type apply to save, edit to reopen the buffer, or press Enter to cancel. --dry-run stops after the preview and saves nothing. Invalid documents can be reopened for correction.
Removing a line schedules that key for deletion. KEY= saves an empty value. Deleting every secret requires typing the environment reference. There is no --yes option, and --json is unavailable for this interactive command.
Comments, blank lines, and key ordering survive later CLI and UI sessions. Comments are unencrypted metadata. Put credentials in values, never in comments. Use escaped newlines for multiline values, such as PRIVATE_KEY="first\nsecond". Variable references and command substitutions remain literal text; Dopbase never evaluates them.
The environment must remain unchanged from loading through saving. If another user changes its secrets or layout, Dopbase stops with a conflict. Start a fresh editing session to work from the current values. Failed or uncertain save requests are not automatically retried. Dopbase removes the editor files before submitting a confirmed draft. Once submission starts, an interruption waits for the server response instead of reporting a cancellation while a save may still commit.
Editor security
Known editors use a protected session with isolated configuration and disabled plugins, language servers, swap files, backups, and persistent history where applicable. This means your usual configuration and custom mappings are not loaded. On macOS, a nano alias pointing to Pico is treated as a custom editor. A custom command, including a known editor with extra arguments, requires acknowledgement before values are fetched. Custom editors must wait until editing finishes; a launcher that returns immediately is unsuitable.
Dopbase uses an owner-only session directory under the active client configuration directory's secret-edit folder. The directory has mode 0700 and the .env file has mode 0600. The editor receives a limited environment without Dopbase tokens or unrelated credentials. Unsafe file replacements, symlinks, hard links, and documents larger than 8 MiB are rejected.
Dopbase removes session files after success, cancellation, errors, Ctrl+C, and handled termination signals. A later env edit invocation removes abandoned sessions while preserving active sessions. Cleanup failures report the remaining directory. Linux and macOS are supported.
External editors receive plaintext. Forced termination, power loss, disk snapshots, a compromised editor, or terminal recording can expose it. File deletion does not guarantee forensic erasure. Read the security model for these limits.
Secret commands
secret set securely prompts for a value when attached to a terminal. Use --stdin for automation:
printf '%s' "$NEW_DATABASE_URL" | \
dopbase secret set payment-service/staging DATABASE_URL --stdinDopbase does not provide a plaintext --value argument. --reveal requires interactive password confirmation on every invocation and cannot be bypassed with --json, stdin, or a confirmation flag. Reveal and deletion operations are explicit, permission-controlled, and audited. Normal human and JSON output never contains a value.
Import and export
Import into an existing environment with:
dopbase import payment-service/staging .env.staging
dopbase import payment-service/staging secrets.json
dopbase import payment-service/staging secrets.toml
cat secrets.yml | dopbase import payment-service/staging - --format yamlImport merges by default: keys in the file are created or updated, while remote keys absent from the file remain unchanged. --dry-run reports the number of additions, updates, unchanged values, and deletions without changing server state.
Use --replace to make the remote environment match the file exactly. Replace shows the keys that would be deleted and requires confirmation. Non-interactive use also requires --yes.
The CLI infers JSON from .json, YAML from .yaml or .yml, and TOML from .toml. Every other filename defaults to dotenv, which keeps names such as .env.production compatible. Pass --format <dotenv|json|yaml|toml> to override inference. Stdin uses - and always requires --format.
JSON, YAML, and TOML input must be one flat mapping of string keys to string values. Nested objects or tables, arrays, numbers, booleans, dates, null values, duplicate keys, and empty keys fail the complete import. Dotenv does not expand variables or run command substitutions. All formats allow empty string values but must contain at least one secret. Errors may name a key, but never print its value.
Export requires an explicit destination:
dopbase export payment-service/staging --output .env.staging
dopbase export payment-service/staging --output secrets.json
dopbase export payment-service/staging --output secrets.toml
dopbase export payment-service/staging --stdout --format yamlTo inject secrets into an existing container, use Docker format:
dopbase export payment-service/staging --stdout --format docker |
docker exec \
--env-file=/dev/stdin \
--user node \
-w /workspace \
container-name \
node script.js--output and --stdout are mutually exclusive. File output infers its format from the filename, while stdout defaults to dotenv. --format overrides either default. Docker format is selected explicitly with --format docker; it is not available for import or init. All output formats sort keys for stable exports. Global --json controls command status output and cannot be combined with plaintext --stdout.
Docker env files use raw KEY=value lines. Spaces and extra = characters are part of the value, while quotes are also literal characters. Docker format therefore does not quote or escape values. It rejects secrets containing line breaks or NUL bytes because Docker env files cannot represent them safely. Use a mounted secret file for multiline certificates and private keys.
Place Docker's --env-file option before the container name. The example does not use -i because Docker consumes stdin as the env file. If the program also needs stdin, export to a temporary private file, pass its path to --env-file, and remove the file after the command exits.
File export refuses to overwrite an existing path unless --force is passed and creates the file with restrictive permissions where the platform supports them. Export reveals plaintext values and records access in the audit log. Human CLI exports require interactive password confirmation. Runner tokens can export only their assigned environment without a prompt, using DOPBASE_TOKEN or an encrypted saved runner credential. AI agent tokens cannot export values.
Exports require a live server response. They never fall back to the encrypted run cache. Authentication, network, or rendering failures leave an existing output file untouched.
The Admin UI provides the same workflow for dotenv files, with a visual review and dry-run summary before anything is stored. See import and export.
Export in AWS CodeBuild
Install Dopbase in the build image and use a runner token scoped to the target environment. Store a JSON secret containing a token field in AWS Secrets Manager, for example under dopbase/production. Give the CodeBuild service role secretsmanager:GetSecretValue access to that secret. CodeBuild injects it as DOPBASE_TOKEN through env.secrets-manager:
version: 0.2
env:
shell: bash
variables:
DOPBASE_URL: https://dopbase.example.com
secrets-manager:
DOPBASE_TOKEN: "dopbase/production:token"
phases:
build:
commands:
- |
(
set -eu
set +x
secrets_dir=$(mktemp -d)
trap 'rm -rf "$secrets_dir"' EXIT
dopbase export env_482731 --output "$secrets_dir/.env"
./deploy.sh "$secrets_dir/.env"
)Replace the environment ID and deployment command with your own. The build must be able to reach the Dopbase server. The shell exits if export fails and removes its temporary secrets directory when the block ends. Keep .env out of build logs, source control, container image layers, and ordinary build artifacts. No dopbase login step is needed.
AWS Systems Manager Parameter Store is another option, using env.parameter-store and the corresponding IAM permissions. See the AWS CodeBuild buildspec reference for both integrations and permissions, including KMS requirements.
Runner tokens
Create a different token for each deployed environment:
dopbase token create payment-service/production \
--name production-server --role runner
dopbase token create payment-service/production \
--name deploy-job --expires-in 12hThe plaintext token is displayed only once. Tokens can also be created and revoked on an environment's Tokens tab in the Admin UI. Without --expires-in, a runner token does not expire. Use never or a whole number followed by h or d, up to 26280h or 1095d. The server rejects expired tokens even if the client's clock is wrong. The list shows each token's expiry and status. A runner token can retrieve values for dopbase run and export them from its assigned environment. It cannot modify secrets or access another environment. Export audit entries identify the runner token and secret count without storing values.
Run a process
Pass the environment directly:
dopbase run payment-service/development -- npm run devOn an application server, save its runner token once:
printf '%s' "$RUNNER_TOKEN" | dopbase login --token
dopbase run payment-service/production -- npm startFor CI jobs, inject DOPBASE_TOKEN through the pipeline's secret store:
dopbase run payment-service/production -- npm startAutomation may set DOPBASE_ENV instead:
DOPBASE_ENV=env_482731 dopbase run -- ./payment-serviceInteractive users may save a server-scoped default:
dopbase env default payment-service/development
dopbase run -- npm run devAn explicit positional environment takes precedence over DOPBASE_ENV, which takes precedence over the saved default. If none is available, run explains how to set the default. Use dopbase env default --clear to remove it. An empty DOPBASE_ENV is an error and does not fall back.
Before starting the child, Dopbase writes the resolved project, environment, immutable ID, loaded key count, and whether values came from the live server or encrypted cache to standard error. It does not print values.
Managed values override same-named variables inherited from the parent process. Dopbase authentication variables are removed from the child environment so the child application does not receive the credential used to contact Dopbase.
Every successful live retrieval refreshes the credential-bound encrypted cache. Connection failures, timeouts, and 5xx responses fall back to the latest matching cache after a five-second live-fetch deadline.
Cached entries do not expire, so the warning includes their fetch time and age. Authentication, authorization, not-found, malformed-response, missing-cache, or cache-integrity failures stop before the child starts. Once started, signals are forwarded and the child's exit status is returned to the calling shell.
Runtime cache maintenance
Inspect safe metadata for the active server's encrypted runtime cache:
dopbase cache list
dopbase cache list --jsonThe output includes the server URL, project and environment names, immutable environment ID, fetch time, age, and aliases. It never includes secret names, values, cache keys, nonces, or ciphertext.
Remove entries older than 14 days:
dopbase cache clean --dry-run
dopbase cache clean --yesSet a different age with a positive whole number followed by s, m, h, or d. An entry must be strictly older than the cutoff, so an entry exactly 14 days old is kept by the default cleanup.
dopbase cache clean --older-than 30d --yes
dopbase cache clean --all --yesOnly --all ignores age. Cleanup asks for confirmation unless --yes is present. --dry-run never writes to the cache and does not ask for confirmation. These commands work offline, but the active credential must be able to unlock the cache.
backup
Create an encrypted system-level snapshot containing all projects, environments, secrets, runner tokens, and administrator credentials.
# Create a timestamped backup stored on the server
dopbase backup
# Create a named backup and save a copy locally
dopbase backup pre-upgrade --output ./pre-upgrade.dop
# Run with structured JSON output
dopbase backup pre-upgrade --jsonOperation flow
- Dopbase contacts the server and verifies that the instance is running and reachable (
server_status: connected (live)). - The server acquires an online SQLite snapshot lock, generates
dopbase.dbandmanifest.json, and encrypts the ZIP container using XChaCha20-Poly1305 with the server's master key (~/.dopbase/master.key). - The encrypted
.doparchive is stored on the server under~/.dopbase/backups/. - If
--outputwas specified, the CLI streams and downloads the archive to your local device. - The CLI prints a confirmation and a security notice reminding you that the backup is encrypted with this instance's master key and that the master key will be required if restoring onto a new server.
IMPORTANT
dopbase backup requires an active, reachable server (server_status: connected (live)). If the server is offline or disconnected, the command halts immediately.
restore
Restore all database tables and instance configuration from a .dop backup archive.
# Restore on the same server (uses server's existing master key)
dopbase restore ./pre-upgrade.dop
# Restore on a new or different server (Dual-input restore with master.key file)
dopbase restore ./pre-upgrade.dop --key /path/to/source/master.key
# Restore on a new server using a 64-character hex master key
dopbase restore ./pre-upgrade.dop --key 4a2f8b9c01234567...
# First run: start without DOPBASE_ROOT_EMAIL, or use `server setup --web`
# Use the setup token printed by that target listener
dopbase restore ./pre-upgrade.dop --setup-token setup_... --yesOperation flow
- On a live, initialized server:
- Verifies server status is live (
connected (live)). - Uploads the
.doparchive to the server. - Prompts for interactive confirmation (requiring typing
RESTORE) unless--yesis specified. - Decrypts and authenticates the archive using the provided
--key(or the server's existing master key). - If
--keywas provided, re-keys restored secret metadata to the target server's existing~/.dopbase/master.key. - Replaces SQLite database tables, runs any pending migrations, and preserves the active administrator session.
- Verifies server status is live (
- On a first-run uninitialized server:
- Start with no bootstrap email, or use
server setup --web; restoration requires the printed one-time setup token.
- Start with no bootstrap email, or use
IMPORTANT
dopbase restore strictly requires the server to be live and connected (server_status: connected (live)). Offline restores are rejected to prevent file system races and corruption.
Server administration
Offline maintenance commands operate directly on the server database:
dopbase admin reset-password admin@example.com
dopbase admin factory-reset
dopbase admin factory-reset --no-backupadmin reset-password performs offline recovery on the host machine. Because it accesses SQLite files directly, the background or foreground server process must be stopped first to avoid database locks.
The command requires an interactive terminal, prompts for a new password (12 to 128 characters), updates the stored Argon2id hash, and immediately revokes all active sessions for that account.
admin factory-reset also requires the server to be stopped. It displays the exact data directory, then requires please-wipe-out-system and the Dopbase root password. There is no non-interactive bypass.
By default, the reset saves the whole data directory to a timestamped ZIP next to that directory, then removes the active data. The ZIP includes every database, master-key, configuration, backup, log, and local CLI file stored inside the directory. Start again to enter automatic setup on the fresh instance. An interrupted web reset still requires explicit setup to finish its pending work.
Pass --no-backup to remove the data directory without creating the ZIP. The same confirmation phrase and root password are still required.
Structured output
Resource and metadata commands support --json for automation. Secret values remain excluded unless the user explicitly selected --reveal, --stdout, or an export destination. Errors identify the server, project, environment, and operation when safe without including request bodies, tokens, or plaintext values.