ccloud CLI: Document new commands from SDK v6 update (ccloud-private#122) by jordanlewis · Pull Request #22950 · cockroachdb/docs

jordanlewis · 2026-03-04T03:26:15Z

Summary

Documents all new command groups added in cockroachlabs/ccloud-private#122, which updated the ccloud CLI from SDK v3 to v6 and added comprehensive support for new Cloud API features.

New commands documented

Cluster commands

Command	Subcommands	Description
`ccloud cluster connection-string`	—	Get a formatted connection string
`ccloud cluster database`	`list`, `create`, `delete`	Manage databases within a cluster
`ccloud cluster backup`	`list`, `config get`, `config update`	View backups and manage backup configuration
`ccloud cluster restore`	`list`, `create`	Restore from backups
`ccloud cluster versions`	—	List available CockroachDB major versions
`ccloud cluster version-deferral`	`get`, `set`	Manage version upgrade deferral (Advanced)
`ccloud cluster blackout-window`	`list`, `create`, `delete`	Manage maintenance blackout windows (Advanced)
`ccloud cluster maintenance`	`get`, `set`, `delete`	Configure maintenance windows (Advanced)
`ccloud cluster disruption`	`get`, `set`, `clear`	Manage disruption budget (Advanced)
`ccloud cluster cmek`	`get`	View CMEK configuration (Advanced)
`ccloud cluster log-export`	`get`, `enable`, `disable`	Configure log export (Advanced)
`ccloud cluster metric-export`	`cloudwatch`, `datadog`, `prometheus` (each: `get`/`enable`/`disable`)	Configure metric export (Advanced)
`ccloud cluster networking egress-rule`	`list`, `create`, `delete`	Manage egress traffic rules (Advanced)
`ccloud cluster networking egress-private-endpoint`	`list`, `get`, `create`, `delete`	Manage egress private endpoints (Advanced)
`ccloud cluster networking client-ca-cert`	`get`, `set`, `update`, `delete`	Manage client CA certificates (Advanced)
`ccloud cluster networking private-endpoint`	`services`, `create-services`, `connections`, `add-connection`, `delete-connection`	Manage private endpoint connectivity (Advanced)

Top-level commands

Command	Subcommands	Description
`ccloud organization get`	—	View organization information
`ccloud audit list`	—	View audit logs
`ccloud billing invoice`	`list`, `get`	View invoices and billing
`ccloud folder`	`list`, `get`, `create`, `update`, `delete`, `contents`	Manage folders
`ccloud service-account`	`list`, `get`, `create`, `delete` + `api-key` subcommands	Manage service accounts
`ccloud jwt-issuer`	`list`, `get`, `create`, `update`, `delete`	Manage JWT/OIDC issuers
`ccloud replication`	`list`, `get`, `create`, `update`	Manage physical cluster replication

Notes

All Advanced/Dedicated-only features are wrapped in the existing filter-content section pattern
New sections follow the established formatting: {% include_cached copy-clipboard.html %} before code blocks, ~~~ shell for commands, ~~~ for output
Example output is realistic but uses placeholder IDs
This is a draft PR — please review for accuracy and completeness before merging

netlify · 2026-03-04T03:26:34Z

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Name	Link
🔨 Latest commit	`9cb05d4`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-interactivetutorials-docs/deploys/69c30ed7575f8d0008ce84d2

github-actions · 2026-03-04T03:26:37Z

Files changed:

src/current/_includes/cockroachcloud/limitations/limitation-ccloud-folders.md:

Warning: include not used in any cockroachcloud file or include

src/current/_includes/v26.1/sidebar-data/cloud-deployments.json
src/current/cockroachcloud/ccloud-get-started.md
src/current/cockroachcloud/ccloud-reference.md
src/current/cockroachcloud/cloud-sso-sql.md
src/current/cockroachcloud/folders.md
src/current/cockroachcloud/managing-access.md
src/current/releases/cloud.md

netlify · 2026-03-04T03:27:03Z

✅ Deploy Preview for cockroachdb-api-docs canceled.

Name	Link
🔨 Latest commit	`9cb05d4`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-api-docs/deploys/69c30ed71673a3000870eec5

netlify · 2026-03-04T03:38:52Z

✅ Netlify Preview

Name	Link
🔨 Latest commit	`9cb05d4`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-docs/deploys/69c30ed702570100082bfe2c
😎 Deploy Preview	https://deploy-preview-22950--cockroachdb-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

fantapop

Okay, I made it through the whole thing. There are some docs specific comments and some ccloud cli specific comments. I'm fine taking the ccloud ones as later improvements to the CLI.

src/current/cockroachcloud/ccloud-get-started.md

fantapop · 2026-03-05T21:40:19Z

src/current/cockroachcloud/ccloud-get-started.md

+f2a3b4c5-d6e7-8901-2345-678901abcdef  Production                 FOLDER
+a3b4c5d6-e7f8-9012-3456-789012abcdef  Staging       /Production  FOLDER


This example is weird. The full path of the staging folder is /Production/Staging/

@jhlodin I noticed we're still using this weird example. You closed this with no comment.

src/current/cockroachcloud/ccloud-get-started.md

jhlodin · 2026-03-09T20:22:21Z

Pushed a commit that refactors this content into two pages, one to retain the "get started" content for installation and connecting to a Cloud org, the rest that splits out all of the ccloud tasks into separate sections like what we have for the CCAPI https://www.cockroachlabs.com/docs/cockroachcloud/cloud-api

jhlodin

Pushed my own commit to refactor this PR, tagging in another writer to give this a proper peer review

taroface

Just adding a few initial comments -- I'll let another team member do a full review.

src/current/cockroachcloud/ccloud-reference.md

taroface · 2026-03-12T21:34:46Z

src/current/cockroachcloud/ccloud-reference.md

+
+The `ccloud cluster create` command creates a new CockroachDB {{ site.data.products.cloud }} cluster in your organization with the desired plan.
+
+### Create a {{ site.data.products.basic }} cluster


The current version of this doc has the variations of this command in filter tabs, which I find friendlier than stacking the three subcommands directly. Would suggest doing that here, unless we are trying to avoid the tabs due to the upcoming docs migration.

I removed the tabs because of the upcoming docs migration, yeah. I think we also need to do testing to see if hiding content with a filter tab-like system obfuscates an agent reader's ability to associate commands with the relevant Cloud plan.

src/current/cockroachcloud/ccloud-reference.md

bsanchez-the-roach

The main themes of this review:

It sort of feels like there wants to be a succinct, table version of this list of commands at the top of the page? An exhaustive list, and each of those commands in the table would then link down to the more verbose explanation below? Optional, but I think that would add to the human-readability of this page.
I think one of the main things that's consistently missing is links to relevant topics in the Cloud docs (or deployment-agnostic docs). I've added several comments about where to do this (an easy example is CMEK, link to the CMEK docs), but I think there are probably a ton of other places you can do this. Would also add to the human-readability of the page. I think this is a decent use case for Claude, ask "hey review this doc and tell me where I should be linking to other parts of our documentation." It'll give you false positives but just throw those out.
Because for most of these commands, the main input is just a cluster name, most examples are super clear. The reader is familar with the "blue-dog" cluster name and so it doesn't require much explanation. But for any command whose input isn't just a cluster name, there might need to be some extra explanation about what inputs are expected/permitted. This starts to be more relevant from "Manage folders" and below. Are Names allowed, or just IDs? I deduced that ccloud service-account api-key create takes a service account ID, but that required a little too much work on my part. For PCR, what is the prod-east of ccloud replication list prod-east ? Or is that a part of the command name? There's a bit too much room for error in some of these commands at the bottom.

(EDIT: After having thought about this more, you might actually even want to specify further for the cases where the input is just blue-dog, as the idea that that's a cluster name is introduced early on in the page, but a human reader may not be traversing this page linearly and so might not get that.)

bsanchez-the-roach · 2026-03-23T14:55:55Z

src/current/cockroachcloud/ccloud-get-started.md

-## Limitations
-
- {% include cockroachcloud/limitations/limitation-ccloud-folders.md %}
+Refer to the [`ccloud` reference documentation]({% link cockroachcloud/ccloud-reference.md %}) to learn how to use the `ccloud` CLI tool to create and manage CockroachDB {{ site.data.products.cloud }} clusters.


Is there a rule around what pages need a "See also" section? I mean I think it makes sense that this page doesn't have one, it just seems relatively rare in our docs so it somehow looks wrong.

I don't think it's formalized anywhere, maybe something the templating working group considered. But while I think "See also" is a good default for most pages, "Next steps" is a better fit for a how-to (especially a "get started" type page) where it is expected that you will read the page front to back and then take additional steps. I don't think anyone is reading this page and then not going to the reference page to do more stuff with ccloud.

src/current/cockroachcloud/ccloud-reference.md

bsanchez-the-roach · 2026-03-23T15:36:30Z

src/current/cockroachcloud/ccloud-reference.md

+ccloud cluster create basic
+~~~
+
+This command creates a CockroachDB {{ site.data.products.basic }} cluster in the default cloud infrastructure provider (GCP) and the closest region for that provider. It will generate a cluster name.


Could be good to link to where in the docs we mention GCP being the default? This reads as though this knowledge is kind of assumed.

It's only the default for ccloud, not any other deployment tool AFAIK. So it's not so much assumed knowledge as it is a stated fact for the command described here.

bsanchez-the-roach · 2026-03-23T16:33:56Z

src/current/cockroachcloud/ccloud-reference.md

+    ccloud cluster sql blue-dog --sso
+    ~~~
+
+Use the `ccloud auth whoami` command to check that you are logged into the correct organization.


Include link to "organization" docs?

Same as above

src/current/cockroachcloud/ccloud-reference.md

bsanchez-the-roach

Found a few typos but otherwise LGTM

laurenbarker · 2026-03-24T21:29:52Z

@jhlodin are you planning to rebase and merge this PR are you waiting for someone else to do it?

Documents all new command groups added in cockroachlabs/ccloud-private#122, which updated the ccloud CLI from SDK v3 to v6 and added comprehensive support for new Cloud API features. New command groups documented: - ccloud cluster connection-string - ccloud cluster database (list/create/delete) - ccloud cluster backup (list/config get/config update) - ccloud cluster restore (list/create) - ccloud cluster versions - ccloud cluster version-deferral (get/set) - ccloud cluster blackout-window (list/create/delete) - ccloud cluster maintenance (get/set/delete) - ccloud cluster disruption (get/set/clear) - ccloud cluster cmek get - ccloud cluster log-export (get/enable/disable) - ccloud cluster metric-export (cloudwatch/datadog/prometheus) - ccloud cluster networking egress-rule (list/create/delete) - ccloud cluster networking egress-private-endpoint (list/get/create/delete) - ccloud cluster networking client-ca-cert (get/set/update/delete) - ccloud cluster networking private-endpoint (services/connections/etc.) - ccloud organization get - ccloud audit list - ccloud billing invoice (list/get) - ccloud folder (list/get/create/update/delete/contents) - ccloud service-account (list/get/create/delete + api-key management) - ccloud jwt-issuer (list/get/create/update/delete) - ccloud replication (list/get/create/update)

- backup config update: --frequency-minutes/--retention-days → --frequency/--retention - restore create: backup ID is --backup-id flag, not positional arg; add --source-cluster-id and --type - version-deferral set: policy is --policy flag, not positional; list valid values - maintenance set: add required --duration flag, document --offset alternative, fix output format - disruption: rewrite section - it's disruption simulation, not "disruption budget" - log-export enable: --log-group → --log-name; fix output format - egress-rule create: remove nonexistent --ports flag; add --description - egress-private-endpoint create: --name/--service-name → --region/--target-service-identifier/--target-service-type - private-endpoint: fix command names (services → service list, add-connection → connection add, etc.) - private-endpoint: add missing trusted-owner subcommand group (list/add/remove) - replication create: --source-cluster/--target-cluster → --primary-cluster/--standby-cluster - replication update: --cutover → --status FAILING_OVER; add --failover-at - replication list: add required cluster name argument - folder list: PARENT ID → PARENT PATH, add TYPE column - Fix output table columns across multiple commands to match actual CLI output Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Verified all new command documentation against the actual ccloud codebase (testdata files and source code) and corrected: - Output formats: backup config/versions/version-deferral/cmek/client-ca-cert/ org get all use key-value format, not tables - Column names: backup list (AS OF TIME), versions (RELEASE TYPE/SUPPORT STATUS/SUPPORT END/ALLOWED UPGRADES), billing (STATUS/TOTAL), folder contents (ID/NAME/TYPE/PARENT PATH), service-account list (no CREATOR) - Status values: restore (SUCCESS/PENDING), egress-private-endpoint (AVAILABLE/PENDING), replication create (STARTING) - Positional args vs flags: folder create, service-account create, api-key create all take name as positional arg not --name flag; api-key list uses --service-account-id flag; api-key delete takes 1 arg not 2 - Connection string output includes Connection String header and Parameters section - Prometheus uses "metric scrape endpoint" not "metric export" - Various output message formatting (Successfully vs Success!, casing) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- CloudWatch/Datadog/Prometheus enable: add missing Cluster and Status lines to match source code output - Prometheus enable: revert incorrect "scrape endpoint" wording back to "metric export" to match source - Datadog enable: fix --site flag value to uppercase (US5) to match expected enum values - client-ca-cert set/update: fix "Success!" prefix to "Successfully" and add Status line to match source Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-authored-by: bsanchez-the-roach <brandon.sanchez@cockroachlabs.com>

jordanlewis requested a review from fantapop March 4, 2026 03:27

laurenbarker requested a review from a team March 4, 2026 19:36

jordanlewis marked this pull request as ready for review March 4, 2026 19:43

fantapop reviewed Mar 5, 2026

View reviewed changes

jhlodin force-pushed the jl/ccloud-cli-new-commands-docs branch from 8bf5c03 to 7bc8c15 Compare March 9, 2026 19:02

jhlodin reviewed Mar 9, 2026

View reviewed changes

jhlodin force-pushed the jl/ccloud-cli-new-commands-docs branch from 6324f11 to c05190e Compare March 9, 2026 20:37

taroface reviewed Mar 12, 2026

View reviewed changes

bsanchez-the-roach reviewed Mar 23, 2026

View reviewed changes

jhlodin force-pushed the jl/ccloud-cli-new-commands-docs branch from 33b9e40 to 0a0beb3 Compare March 23, 2026 17:51

bsanchez-the-roach reviewed Mar 23, 2026

View reviewed changes

bsanchez-the-roach self-requested a review March 23, 2026 19:28

bsanchez-the-roach approved these changes Mar 23, 2026

View reviewed changes

fantapop approved these changes Mar 24, 2026

View reviewed changes

jordanlewis and others added 10 commits March 24, 2026 18:22

Refactor into reference vs get started content

cd2819f

Fix links

028cf29

Ryan comments

f6d95d8

Apply suggestions from code review

78f40c4

Co-authored-by: bsanchez-the-roach <brandon.sanchez@cockroachlabs.com>

Address Brandon comments

9afddaf

Fix typos

1f17bc4

jhlodin force-pushed the jl/ccloud-cli-new-commands-docs branch from f6a907c to 1f17bc4 Compare March 24, 2026 22:22

Correct plan names

9cb05d4

jhlodin enabled auto-merge (squash) March 24, 2026 22:23

jhlodin merged commit 192bb12 into main Mar 24, 2026
7 checks passed

jhlodin deleted the jl/ccloud-cli-new-commands-docs branch March 24, 2026 22:37

		f2a3b4c5-d6e7-8901-2345-678901abcdef Production FOLDER
		a3b4c5d6-e7f8-9012-3456-789012abcdef Staging /Production FOLDER


		The `ccloud cluster create` command creates a new CockroachDB {{ site.data.products.cloud }} cluster in your organization with the desired plan.

		### Create a {{ site.data.products.basic }} cluster

Conversation

jordanlewis commented Mar 4, 2026

Summary

New commands documented

Cluster commands

Top-level commands

Notes

Uh oh!

netlify bot commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Uh oh!

github-actions bot commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Files changed:

Uh oh!

netlify bot commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cockroachdb-api-docs canceled.

Uh oh!

netlify bot commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Netlify Preview

Uh oh!

fantapop left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jhlodin commented Mar 9, 2026

Uh oh!

jhlodin left a comment

Choose a reason for hiding this comment

Uh oh!

taroface left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jhlodin Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bsanchez-the-roach left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

netlify bot commented Mar 4, 2026 •

edited

Loading

github-actions bot commented Mar 4, 2026 •

edited

Loading

netlify bot commented Mar 4, 2026 •

edited

Loading

netlify bot commented Mar 4, 2026 •

edited

Loading

jhlodin Mar 19, 2026 •

edited

Loading

bsanchez-the-roach left a comment •

edited

Loading