Reference

CLI reference

The dibbla CLI is the primary way to ship code, manage applications, databases, secrets, and workflows on the Dibbla platform — and to scaffold projects, run task pipelines, and install AI-agent skills locally.

The dibbla binary covers the full lifecycle of a Dibbla project: authenticate, scaffold, run task pipelines locally, deploy, manage applications and managed Postgres databases, set secrets, build workflows, and install skills that teach AI coding agents how to drive the CLI.

Install

# macOS / Linux
$curl https://install.dibbla.com -fsS | sh

# Windows
$irm https://install.dibbla.com/install.ps1 | iex

# macOS / Linux
$brew install dibbla-agents/tap/dibbla

You can also grab a binary directly from GitHub Releases, which is where the .deb/.rpm packages and previous versions live.

The script installers fetch everything — version list, archive and checksums — from install.dibbla.com, and verify the archive’s SHA-256 before writing it to disk. No GitHub call is involved, which is what makes the CLI installable from inside AI coding-agent sandboxes such as Claude Cowork. See Get started with the CLI.

Verify

$dibbla --version
dibbla version 1.2.33
 
$dibbla --help
Dibbla CLI helps you create and manage Dibbla worker projects.
...

Top-level flags

Flag	Purpose
`-h`, `--help`	Show help for `dibbla` or any subcommand.
`-v`, `--version`	Print the installed version and exit.
`--context <name>`	Run this one command against the named context, without changing the one in use.
`--org <id>`	Act as this organization for this one command, overriding `DIBBLA_ORG_ID` and the pin on the active context.
`--skill-prompt`	Print the bundled LLM-oriented skill prompt — paste it into an agent that doesn’t yet have the skill installed.

Workflow commands (workflows, nodes, edges, inputs, tools, revisions, functions) accept three additional global flags:

Flag	Purpose
`-o`, `--output yaml\|json\|table`	Output format. Default depends on the subcommand.
`-q`, `--quiet`	Minimal output, suitable for scripting.
`-v`, `--verbose`	Log raw HTTP request/response — handy when debugging.

Environment variables

The CLI reads credentials and overrides from the shell, then ./.env (loaded automatically), and only then from the context you are using — whose token lives in the OS keyring under a per-context key. Setting DIBBLA_API_TOKEN, in the shell or in .env, bypasses the context layer entirely, which is what keeps CI and one-shot scripted calls unaffected.

Variable	Purpose
`DIBBLA_API_TOKEN`	Bearer token used for every API call. Set this in CI to skip `dibbla login` entirely.
`DIBBLA_API_URL`	API endpoint. Default `https://api.dibbla.com`.
`DIBBLA_AUTH_SERVICE_URL`	Legacy alias for `DIBBLA_API_URL`. Read if the primary variable is unset.
`DIBBLA_CONTEXT`	Point this shell at one context. Below `--context`, above `dibbla context use`.
`DIBBLA_ORG_ID`	Act as this organization, overriding the pin stored on the active context.
`DIBBLA_DB_HOST`	Override the database proxy host derived from `DIBBLA_API_URL`.
`DIBBLA_DB_PORT`	Override the database proxy port (default `30432`).
`DIBBLA_DB_SSLMODE`	Override the auto-detected `sslmode` (`require` for prod, `disable` for internal/local).
`DIBBLA_TEMPLATES_URL`	Override the hosted template manifest — useful for staging or local manifests.
`DIBBLA_NO_UPDATE_NOTIFIER`	Set to `1` to disable the background “new release available” check.

`.env` is loaded automatically.

When dibbla starts, it loads variables from ./.env in the current directory before reading any context or keyring entry. Use dibbla login --write-env to seed .env with DIBBLA_API_TOKEN and DIBBLA_API_URL and ensure .env is listed in ./.gitignore.

Commands

dibbla login

Authenticate with the Dibbla API. Browser OAuth, paste-token, or --api-key for non-TTY contexts.

dibbla context

Stay logged in to several API servers at once — production, a self-hosted instance, a customer’s — and switch with one command.

dibbla deploy & apps

Ship a containerized app, then list, inspect, update, or delete it.

dibbla apps checks

List, run, and review an app’s application checks — JSON output and exit codes CI can gate on.

dibbla apps maintenance

Operate the maintenance agent and review its proposals — JSON, product exit codes, and a server-owned decision object.

dibbla db

Provision Postgres databases, connect via the proxy, and dump/restore with pg_dump.

dibbla storage

Provision S3 buckets with a hard quota and bucket-scoped credentials, injected into your apps as secrets.

dibbla secrets & env

Set and request write-only secrets, pull the app’s environment to a local .env.local, and promote a plain env var to a secret.

dibbla export

Take an app with you — source, databases, buckets, environment and manifest in standard formats, with a docker compose sketch that runs it.

dibbla run

Execute a dibbla-task.yaml pipeline locally — file, URL, or preview-only.

dibbla template & create

Discover hosted templates, install one into a directory, or scaffold a Go worker from scratch.

dibbla skills

Install bundled skills so Claude Code, Cursor, Gemini CLI, and other agents can drive dibbla for you.

dibbla workflows

Build, version, and execute workflows — plus the nodes, edges, inputs, tools, revisions, and functions sub-trees.

dibbla feedback

Send feedback to the Dibbla team and review what your org has filed.

Quick index

Command	What it does
`dibbla login` / `logout`	Store or remove API credentials.
`dibbla context list \| use \| current \| rename \| rm`	Switch between several API servers.
`dibbla upgrade [--open] [--json]`	Payment link to move a trial to Business.
`dibbla create go-worker`	Scaffold a new Go worker project.
`dibbla deploy`	Build and ship the current directory.
`dibbla apps list \| get \| update \| delete`	Inspect and modify deployed apps.
`dibbla apps checks list \| run \| history \| enable \| disable`	Application checks, with JSON and CI exit codes.
`dibbla apps maintenance status \| enable \| run \| runs`	Maintenance agent: settings, one run, history.
`dibbla apps proposals list \| show \| approve \| deny \| retry`	Change queue: inspect and decide, server-owned.
`dibbla db list \| create \| delete \| dump \| restore \| connect`	Managed Postgres lifecycle.
`dibbla secrets list \| set \| request \| import \| delete`	Write-only secrets: global, per app, per service.
`dibbla env pull \| promote`	The app’s environment locally; env var → secret.
`dibbla run [path-or-url]`	Execute a `dibbla-task.yaml` pipeline locally.
`dibbla template list \| install`	Hosted starter templates.
`dibbla skills list \| install`	Install agent skills into a project or `$HOME`.
`dibbla workflows ...` (alias `wf`)	Workflow CRUD, validation, execution, API docs.
`dibbla nodes \| edges \| inputs \| tools`	Edit a workflow’s structure.
`dibbla revisions ...` (alias `rev`)	Snapshot and restore workflow revisions.
`dibbla functions ...` (alias `fn`)	Browse the function registry.
`dibbla feedback <message>`	Send feedback to the Dibbla team.
`dibbla completion bash\|zsh\|fish\|powershell`	Print a shell completion script.

Shell completion

Generate completion scripts for your shell with dibbla completion <shell>. The output is a script you source — exact placement depends on your shell’s conventions.

$dibbla completion zsh > "${fpath[1]}/_dibbla"
# Then restart your shell

$dibbla completion bash | sudo tee /etc/bash_completion.d/dibbla > /dev/null

$dibbla completion fish > ~/.config/fish/completions/dibbla.fish

$dibbla completion powershell | Out-String | Invoke-Expression

Update notifications

On interactive terminals, dibbla checks GitHub for new releases at most once every 24 hours. The check is non-blocking, so --help and --version always return immediately. Set DIBBLA_NO_UPDATE_NOTIFIER=1 to disable it.

← Previous

Core concepts

dibbla login