Organizations

Most ccp commands operate on a specific organization — the one that owns the App, Project, database, or domain you're working with. ccp org lets a multi-org account choose one by name once and stop passing --org-id (or setting CCP_ORG_ID) on every call.

Set a Default

ccp org use
# ? Which Organization?
#   Acme Inc (default)
#   Beta Corp

Run interactively with no arguments, ccp org use lists your organizations by name — disambiguating duplicates with their ID — marks the current saved default, and saves your selection:

ccp org use org_abc123
# Default organization set to Acme Inc.

Pass an ID directly to skip the picker. Either way, the organization must be one you can access — ccp org use validates it before saving.

Check the Effective Organization

ccp org current
# Acme Inc (org_abc123) — saved_default

ccp org current --json
# {"organization_id":"org_abc123","name":"Acme Inc","source":"saved_default"}

current reports the organization a command would resolve to right now, and where that came from (source), without prompting. Use it to debug an unexpected org before running a mutating command.

Clear the Default

ccp org clear
# Saved default organization cleared.

Removes only the saved default for this account, API environment, and issuer — nothing else is affected. Safe to run even if no default was ever set.

Where the Default Fits in Org Resolution

A saved default is one input among several. The full precedence, highest first:

1. --org-id flag / project binding (e.g. a linked .ccp/config.json or cluster.toml)
2. the selected developer context
3. CCP_ORG_ID environment variable
4. the saved default (ccp org use)
5. the sole organization on your account, auto-picked
6. otherwise: the interactive picker in a TTY, or an error in headless mode

So a project's pinned org, a named context, or CCP_ORG_ID all still win over a saved default — the default only fills in when none of those apply. See Headless Mode → Resolving the org for the headless-specific behavior.

Scope and Storage

Saved defaults live under ~/.ccp/org-defaults/, partitioned by API origin, auth issuer, and the authenticated account (its /userinfo subject) — switching CCP_API_URL, auth issuer, or logging in as a different user each gets its own independent default, and one never overwrites another. Defaults persist across shells and survive session-token renewal.

An invalid or now-inaccessible saved default (an org you lost access to, or a corrupted file) fails explicitly with a pointer to ccp org clear or ccp org use <id> rather than silently falling through to a different organization.

ccp org use does not relink or move any existing App, Project, database, or domain — it only changes which organization future ambiguous commands resolve to.

Headless Mode

In headless mode (CCP_HEADLESS=1 or a non-interactive terminal), ccp org use with no ID never guesses: it saves the sole organization you can access, or fails listing every organization if you belong to more than one. ccp org current and ccp org clear never prompt in either mode.