# 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 [#set-a-default]

```bash
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:

```bash
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 [#check-the-effective-organization]

```bash
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 [#clear-the-default]

```bash
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 [#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](/docs/ccp/headless#resolving-the-org-with-ccp_org_id) for the headless-specific behavior.

## Scope and Storage [#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.

<Callout type="info">
  Don't run `ccp org use` inside a Clusterbase-provisioned development VM. Those VMs already have `CCP_ORG_ID` injected for their organization, which outranks a saved default — setting one there has no effect on VM commands and only adds local state to clean up.
</Callout>

## Headless Mode [#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.