capellactl

capellactl is a command-line tool for Couchbase Capella. It creates and manages projects, clusters, buckets, scopes, collections, database credentials and allowed IP ranges with short, readable commands, and keeps a record of your whole environment in one file, capella.yaml.

Why capellactl?

Everything in Capella can be automated through the Capella Management API v4.0, and capellactl is built on it. But calling the API directly is slow work: you look up URL paths, copy organization, project and cluster IDs between calls, write JSON bodies, poll until a cluster is ready, and read through nested responses. Adding one bucket looks like this:

curl -X POST "https://cloudapi.cloud.couchbase.com/v4/organizations/$ORG_ID/projects/$PROJECT_ID/clusters/$CLUSTER_ID/buckets" \
  -H "Authorization: Bearer $CAPELLA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "orders", "type": "couchbase", "storageBackend": "magma", "memoryAllocationInMb": 1024}'

With capellactl you use names instead of IDs, and it asks before changing anything:

capellactl bucket create dev-01 orders --memory 1024 --storage-backend magma

What you get

• Commands that read like the task. cluster create, cluster scale, bucket create, credential create, cidr create: no URLs, IDs or JSON. Leave out an option and capellactl asks for it, with a sensible default.
• A look before every change. Each command shows its plan (what will be created, changed or deleted) and asks [y/N]. Deleting anything that holds data asks you to type its name.
• Waits for you. Cluster deployments, scaling and power changes wait until the cluster is healthy, with progress on screen, and print the connection string when it is ready.
• Your environment in one file. Every command records its change in capella.yaml, which capellactl writes for you. Keep it in Git to see who changed what; capellactl apply rebuilds the whole environment from it, and capellactl sync brings in changes made in the Capella UI. There is no separate state file: Capella is the source of truth.
• Safe by default. Nothing is deleted unless you ask. Changes Capella cannot make in place, such as moving a cluster to another region, are refused instead of done by delete and re-create. Scaling in is checked against bucket memory and replicas first, and deletion protection blocks every way of deleting a cluster.
• Secure credentials. The API key is stored in your OS keychain. Passwords are read from environment variables or files, never written to capella.yaml or printed.
• Ready for scripts and CI/CD. Running apply again when nothing changed reports No changes. Every question has an option, --auto-approve replaces the prompts, -o json gives machine-readable output, and exit codes tell a pipeline what happened (capellactl help ci).
• Saves money. Turn clusters off and on, set an office-hours hibernation schedule, or scale one node at a time within limits.

capellactl 1.0 covers the operations listed in API coverage. For anything else, use the Capella UI or the Management API directly.

Install

capellactl has not had its first release yet, so install it from source. It takes a few minutes and needs Git and Python 3.10–3.13. The steps below are for macOS and Linux; on Windows, follow On Windows (PowerShell).

1. Check your Python version. On many Macs, python3 is older than 3.10:

python3 --version                  # 3.10, 3.11, 3.12 or 3.13 is fine
python3.12 --version               # if python3 is older, try a specific version

If you have no suitable version, install one: brew install python@3.12 on macOS, or from python.org. Ubuntu 22.04 and later already include a suitable python3.

2. Install capellactl. Replace python3.12 with the command that printed a suitable version. Run the commands from the folder that git clone creates, the one that holds pyproject.toml, not from the capellactl/capellactl folder inside it. That is where the .venv environment belongs:

git clone https://github.com/couchbaselabs/capellactl.git && cd capellactl
python3.12 -m venv .venv
.venv/bin/pip install -e .
source .venv/bin/activate          # puts capellactl on your PATH; run again in each new terminal
capellactl --version

capellactl 1.0.0.devN+g… (Management API v4.0)
Licensed under Apache-2.0 · Copyright 2026 Couchbase, Inc.

does not appear to be a Python project: neither 'setup.py' nor 'pyproject.toml' found means pip ran in the wrong folder: cd .. until ls shows pyproject.toml, delete any .venv you created elsewhere, and repeat the steps.

To update later, run git pull in the capellactl folder; the environment picks up the new code. Then continue with Quick start, or the step-by-step getting started guide.

On Windows (PowerShell)

Open Windows PowerShell (Start menu → type PowerShell) and run each command on its own, in order:

Step	Run in PowerShell	You should see / if it fails
1. Install Git and Python 3.12	winget install --id Git.Git -e winget install --id Python.Python.3.12 -e	Then close PowerShell and open it again. No winget: install Git from git-scm.com and Python 3.12 from python.org, not the newest version (capellactl needs 3.10–3.13), and tick Add python.exe to PATH
2. Check Python	py -3.12 --version	Python 3.12.x. If python opens the Microsoft Store, ignore it: use py as shown here
3. Download capellactl	git clone https://github.com/couchbaselabs/capellactl.git cd capellactl	Two separate commands: Windows PowerShell does not accept &&
4. Create its environment	py -3.12 -m venv .venv	A new .venv folder
5. Install it	.venv\Scripts\python -m pip install -e .	Successfully installed … capellactl-…. requires a different Python: step 4 used a Python newer than 3.13; install 3.12 (step 1), delete .venv and repeat step 4
6. Allow activation (once per user)	Set-ExecutionPolicy -Scope CurrentUser RemoteSigned	Answer Y. If your company blocks this, skip steps 6 and 7, and type .venv\Scripts\capellactl.exe wherever the docs say capellactl
7. Activate (in each new window)	.venv\Scripts\Activate.ps1	The prompt starts with (.venv). Without it you get capellactl is not recognized. In cmd.exe: .venv\Scripts\activate.bat
8. Check capellactl	capellactl --version	capellactl 1.0.0.devN+g… (Management API v4.0)
9. Make a folder for your environment	mkdir ~\capella-env cd ~\capella-env	capellactl writes capella.yaml in the folder you run it from

configure keeps the API Key Token in Windows Credential Manager (entry capellactl) and profiles in %APPDATA%\capellactl. The docs show macOS/Linux commands; Using the commands in PowerShell lists the few that are typed differently (passwords in $env:, long commands, pasting the token).

After the first release (1.0.0)

These are not available yet. From 1.0.0 on, each GitHub Release will offer two more ways to install:

• A standalone executable, one file per platform, with nothing else to install (no Python, pip or Docker):

Not released yet: these files are attached to each GitHub Release from 1.0.0 on. Until then, install from source.

Your computer	File	Size	SHA-256
macOS 12+, Apple silicon (M1–M4)	capellactl-<version>-macos-arm64
macOS 12+, Intel	capellactl-<version>-macos-x86_64
Linux x86-64, glibc 2.28+ (RHEL/Rocky 8+, Ubuntu 20.04+, Debian 10+)	capellactl-<version>-linux-x86_64
Linux ARM64, glibc 2.28+ (AWS Graviton, Ampere)	capellactl-<version>-linux-arm64
Windows 10/11 and Server 2019+, 64-bit	capellactl-<version>-windows-x86_64.exe

How to pick, verify and run the right file: downloads/README.md.

• A Python wheel, installed with pipx install ./capellactl-1.0.0-py3-none-any.whl.

Building these files (make dist) and the development setup are in CONTRIBUTING.md.

Quick start

You need a Capella API key (Organization settings → API Keys, with this machine's IP allowed); copy the API Key Token.

capellactl configure                       # saves the token in your OS keychain, writes capella.yaml from Capella
capellactl plan                            # "No changes" for what was discovered
capellactl cluster create nova-dev-02      # asks a few questions, deploys, waits until healthy
capellactl bucket create nova-dev-02 orders --memory 1024
export ORDERS_APP_PASSWORD='Orders-Passw0rd-2026!'
capellactl credential create nova-dev-02 orders_app --privileges read+write --bucket orders --password-env ORDERS_APP_PASSWORD
capellactl sync                            # pick up changes made in the Capella UI

• --memory 1024 is the memory the bucket may use, in MB.
• --privileges read+write --bucket orders lets the app read and write every scope and collection of orders, and nothing else.
• --password-env ORDERS_APP_PASSWORD reads the password from that environment variable. capella.yaml records only ${ORDERS_APP_PASSWORD}.

The getting started guide explains every option of these commands, step by step.

For CI, set CAPELLA_API_KEY and CAPELLA_ORG_ID instead of running configure, and pass --auto-approve (see Options for every command). capellactl help ci has GitHub Actions and GitLab CI examples.

Commands

There are two kinds of command. Resource commands change one thing, such as a cluster or a bucket, in Capella and record it in capella.yaml. Environment commands work on the whole file at once.

Command	What it works on	Subcommands
configure	Your API key and organization (a profile)	list, show, remove
project	Projects	list, get, create, update, delete
cluster	Clusters	options, disk-types, list, get, create, clone, update, scale, power, protect, delete
cluster group	A cluster's service groups	list, add, remove
cluster schedule	A cluster's hibernation schedule	show, set, apply, pause, resume, delete
cluster backup	Backups of a whole cluster	list, create, schedule, retain, restore, restores, regions, delete
cidr	IP ranges allowed to connect to a cluster	list, create, delete
bucket	Buckets	list, get, create, update, delete
bucket backup	Backups of a bucket	list, get, create, schedule, cycle, restore, export, delete
scope, collection	Scopes and collections in a bucket	list, create, delete; collections also update
credential	Database credentials (app logins)	list, get, create, update, delete
init, sync	Write capella.yaml: from questions (init), or from what is in Capella (sync; import is an older name for it)
validate, plan, drift	Check the file, or compare it with Capella; change nothing
apply, destroy	Make Capella match the file, or delete what the file describes
help, completion	Built-in guides (capellactl help topics) and shell completion

Every command takes --help, which lists its options with examples.

Options for every command

These options go before the command name, for example capellactl -o json cluster list:

Option	Meaning
-c, --config PATH	The capella.yaml to use. Default: ./capella.yaml in the current folder (capellactl help config)
--profile NAME	The saved profile, with its API key and organization, to use. Default: default
-o, --output text|json	json prints machine-readable output for scripts
--log-level error|warn|info|debug	How much detail to log; debug shows every API call, with secrets masked
-y, --yes, --auto-approve	Answer y to every confirmation, for scripts and CI
-q, --quiet	Print only errors and results, without progress or hints
--no-wait	Return as soon as Capella accepts a change, without waiting for the cluster to be ready
--timeout DURATION	The longest time to wait for a cluster operation. Default: 60m

Where a setting comes from when it is given more than once, highest first: a command-line option, then an environment variable (CAPELLA_API_KEY, CAPELLA_ORG_ID, CAPELLACTL_CONFIG, CAPELLACTL_PROFILE), then the profile, then organizationId in capella.yaml. capellactl configure show prints each setting and where it came from, and capellactl help exit-codes explains the exit codes.

Passwords are never written to capella.yaml or printed: give them as --password-env VAR or --password-file PATH (recorded as ${VAR} or ${file:PATH}). A password Capella generates is saved once to .capellactl/credentials/, which only you can read.

Documentation

Document	For
Getting started	Step-by-step walkthrough with example output, from install to deleting a cluster, and troubleshooting
Custom clusters and service groups	Any size and service layout: several service groups (MDS) with --group, adding and removing groups, disk types, single-node and advanced options
Backup and restore	Cluster and bucket backup schedules, listing backups, backing up before a change, restoring a cluster or a bucket, downloading a bucket backup
Runbook	Day-2 tasks with the exact command and expected output, a copy-paste reference of every command, and a 20-minute demo script
capella.yaml reference	Every field: type, default, whether it can change, API mapping (generated from the schema)
Examples	Annotated reference, single-node dev, GCP production, Azure production, minimal
Migrating from the scale script	scale_capella_cluster.sh → capellactl
Architecture	Design, idempotency rules, test conventions
Release README	Release plan and user stories
CONTRIBUTING.md	How to build, test and change the project

Couchbase also publishes an official Terraform provider for Capella; capellactl or Terraform? explains when to prefer it.

Project structure

Path	Contents
capellactl/cli/	Commands (click), one module per command group; main.py is the root
capellactl/api/	Management API v4.0 client: auth, retries, pagination, one function per endpoint, typed errors
capellactl/config/	capella.yaml schema, loading, validation rules, comment-preserving edits, profiles and settings
capellactl/resources/	One reconciler per resource kind (project, cluster, bucket, scope, credential, CIDR)
capellactl/engine/	Planner, executor and waiter for long cluster operations
capellactl/importer/, output/, help/	import/sync writer; rendering, redaction and passwords; capellactl help pages
tests/	unit/, contract/ (mocked HTTP), scenario/ (CLI against the fake Capella), integration/ (real Capella)
scripts/	Generators and CI checks: story index, API coverage, AC coverage, third-party notices
docs/	Architecture, user stories (CAP-NNN-*.md), release plan, API coverage, runbook, examples

Build, test and documentation conventions: CONTRIBUTING.md and the Makefile.

Licence

capellactl is licensed under the Apache License 2.0. Copyright 2026 Couchbase, Inc.; see NOTICE. The open-source packages it depends on, and their licences, are listed in THIRD_PARTY_NOTICES.md.