Manage Cabinets | Codiac CLI
A cabinet is a space for running your collection of assets together as an isolated instance of your enterprise. Cabinets are grouped by environment and provisioned on a single cluster.
What you'll get
- Define, create, and restore cabinets
- Understand when a cabinet has infrastructure and when it doesn't
- Move a cabinet from one cluster to another
- Remove a cabinet precisely — keep the definition, remove the infrastructure, or both
Prerequisites
- Codiac account and CLI installed and logged in
- An enterprise and at least one environment (or use a Hosted Sandbox)
The Big Picture: Cabinet Definition vs. Live Infrastructure
Every cabinet in Codiac has two distinct layers:
| Layer | What it is | Created by |
|---|---|---|
| Definition | The blueprint — enterprise, environment, cluster assignment, version history | cabinet define, cabinet create |
| Live infrastructure | The actual running environment provisioned on a cluster | cabinet restore, cabinet create |
These layers are intentionally separable. Codiac stores your cabinet configuration as a durable record independent of whether any infrastructure currently exists. This means:
- You can define a cabinet today and provision it later.
- You can tear down infrastructure and re-create it from the same definition.
- You can define all your cabinets before a single cluster is provisioned — then bring
everything up at once with
cod cluster restore.
Cabinet states
A cabinet can be in one of three states:
| State | What it means |
|---|---|
| Unattached | Definition exists, no cluster assigned yet |
| Attached — no infrastructure | Assigned to a cluster, but no live infrastructure yet |
| Live | Assigned to a cluster with a running instance; infrastructure exists |
Unattached and attached-but-not-provisioned are not error states — they are the intended
starting point for planning ahead. Once you are ready to stand up infrastructure, a single
cod cluster restore realizes everything at once.
The define-first pattern
You can declare your entire cabinet structure — across multiple environments and clusters — before any infrastructure exists. When you are ready to provision:
# Brings up the cluster and provisions all attached cabinets
cod cluster restore my-cluster --silent
This is useful for infrastructure-as-code workflows, staging environment prep, and any situation where you want to review and approve the full blueprint before spending resources.
Cabinet State Reference
The table below describes every cabinet command, the state the cabinet must be in before running it, and the state it will be in after. Use this to plan command sequences and avoid precondition errors.
| Command | Cabinet must be in | Cabinet will be in after |
|---|---|---|
cabinet define | (does not exist yet) | Unattached or Attached — no infrastructure (if --cluster provided) |
cabinet cluster attach | Unattached | Attached — no infrastructure |
cabinet restore | Attached — no infrastructure | Live |
cabinet create | (does not exist yet) | Live |
cabinet destroy | Live | Attached — no infrastructure |
cabinet detach | Any (definition must exist) | Unattached |
cabinet forget | Any (definition must exist) | (definition deleted) |
cabinet obliterate | Any (definition must exist) | (definition deleted, infrastructure removed if live) |
Usage and Options
Use cod cabinet -h to see all available commands:
Define a cabinet
cabinet define creates the cabinet record without provisioning any infrastructure.
Use this when you want to register a cabinet before its cluster is ready, or before
you are prepared to provision.
# Interactive
cod cabinet define
# Scripted — define with a cluster assignment
cod cabinet define my-cabinet \
--enterprise acme \
--environment prod \
--cluster prod-cluster \
--silent
# Scripted — define with no cluster yet (unattached)
cod cabinet define my-cabinet \
--enterprise acme \
--environment prod \
--silent
Automation reference
Required flags (--silent mode): --enterprise, --environment; cabinet name as the first positional argument or via --cabinet
Optional flags: --cluster (omit to leave the cabinet unattached)
Preconditions:
- The enterprise and environment must already exist.
- A cabinet with the same name must not already exist in this enterprise/environment.
Idempotency: Not idempotent — fails if the cabinet already exists. Use cabinet restore to re-provision an existing definition.
State after: Unattached (if no --cluster), or Attached — no infrastructure (if --cluster provided)
Create a cabinet
cabinet create is the all-in-one command: it defines the cabinet and immediately
provisions its infrastructure. It is equivalent to cabinet define followed by
cabinet restore.
# Interactive
cod cabinet create
# Scripted
cod cabinet create my-cabinet \
--enterprise acme \
--environment prod \
--cluster prod-cluster \
--silent
The command runs asynchronously — the CLI blocks and reports back as provisioning completes.
If you want to plan ahead and provision later, use cabinet define now and
cabinet restore when you are ready.
Automation reference
Required flags (--silent mode): --enterprise, --environment, --cluster; cabinet name as the first positional argument or via --cabinet
Optional flags: --correlationId, --socketId (for async event tracking)
Preconditions:
- The enterprise, environment, and cluster must already exist.
- A cabinet with the same name must not already exist in this enterprise/environment.
- The target cluster must have a live instance.
Async behavior: Runs asynchronously on the server. The CLI subscribes to the result and blocks until complete — from a scripting perspective it behaves like a synchronous call. Exit code is non-zero on failure.
Idempotency: Not idempotent — fails if the cabinet already exists.
State after: Live
Restore a cabinet
cabinet restore provisions infrastructure for an existing cabinet definition.
Use this to bring up a cabinet that was defined but not yet provisioned, or to
re-provision a cabinet after its infrastructure was torn down.
# Interactive
cod cabinet restore
# Scripted
cod cabinet restore \
--cabinet my-cabinet \
--enterprise acme \
--environment prod \
--silent
If the cabinet has no cluster assigned, attach one first with cabinet cluster attach.
Automation reference
Required flags (--silent mode): --enterprise, --environment, --cabinet
Optional flags: --correlationId, --socketId (for async event tracking)
Preconditions:
- The cabinet definition must already exist.
- The cabinet must have a cluster assigned (
cabinet cluster attachfirst if not). - The assigned cluster must have a live instance.
Async behavior: Runs asynchronously on the server. The CLI blocks and waits for completion. Exit code is non-zero on failure.
Idempotency: Safe to re-run — re-applies the cabinet definition to the cluster. If infrastructure already exists, it reconciles to the stored definition without failing.
State after: Live
List cabinets
cod cabinet list
View cabinet contents
Lists the asset versions currently running in a cabinet.
cod cabinet contents
Remove a cabinet
Codiac gives you three distinct removal operations, plus a combined shortcut. They differ in what they touch:
| Command | Removes infrastructure | Removes definition |
|---|---|---|
cabinet destroy | ✅ | ❌ |
cabinet forget | ❌ | ✅ |
cabinet obliterate | ✅ | ✅ |
Destroy and forget are the surgical primitives. Obliterate is the shortcut when you want both gone in one step.
cabinet destroy — remove infrastructure, keep definition
Tears down the running infrastructure for a cabinet without deleting the cabinet record.
The definition is preserved, so you can run cabinet restore later to bring it back.
# Interactive
cod cabinet destroy
# Scripted
cod cabinet destroy my-cabinet \
--enterprise acme \
--environment prod \
--silent
Use this when:
- You want to deprovision a cabinet temporarily.
- You are moving the cabinet to a different cluster (destroy → detach → attach → restore).
- You want to clean up infrastructure without losing the cabinet definition and history.
Automation reference
Required flags (--silent mode): --enterprise, --environment; cabinet name as the first positional argument or via --cabinet
Preconditions:
- The cabinet must have a cluster assigned.
- The assigned cluster must have a live instance with active infrastructure for this cabinet.
Idempotency: Not idempotent — fails if no live infrastructure exists (nothing to destroy). Check state before running.
State after: Attached — no infrastructure
cabinet forget — remove definition, leave infrastructure alone
Removes the Codiac record for a cabinet without touching any running infrastructure. The cabinet's running environment (if any) is left intact on the cluster — Codiac simply stops tracking it.
# Interactive
cod cabinet forget
# Scripted
cod cabinet forget my-cabinet \
--enterprise acme \
--environment prod \
--silent
Use this when:
- The cabinet's infrastructure no longer exists and you want to clean up the stale record.
- You want Codiac to stop managing a cabinet whose infrastructure you are keeping for other purposes.
Automation reference
Required flags (--silent mode): --enterprise, --environment; cabinet name as the first positional argument or via --cabinet
Preconditions: The cabinet definition must exist.
Idempotency: Safe to re-run — deletes the record if it exists; no-op if already gone.
State after: Definition deleted. Infrastructure (if any) is untouched.
cabinet obliterate — remove everything
Tears down infrastructure and removes the definition in one step. Equivalent to
cabinet destroy followed by cabinet forget.
# Interactive
cod cabinet obliterate
# Scripted
cod cabinet obliterate my-cabinet \
--enterprise acme \
--environment prod \
--silent
Use this when you are done with the cabinet entirely and want no trace of it in Codiac.
Automation reference
Required flags (--silent mode): --enterprise, --environment; cabinet name as the first positional argument or via --cabinet
Preconditions: The cabinet definition must exist. If the cabinet is live, the cluster must also have a live instance (to tear down infrastructure). If the cabinet has no infrastructure, the definition is still deleted.
Idempotency: Partial — if infrastructure does not exist, the definition is still deleted cleanly. Safe to re-run if the first attempt failed after destroy but before the record was removed.
State after: Definition deleted, infrastructure removed.
Detach a cabinet
cabinet detach clears the cluster assignment from a cabinet definition. The definition
is preserved and the cabinet's infrastructure (if any) is left untouched — Codiac simply
removes the association between the cabinet and its cluster.
After detaching, the cabinet is in an unattached state. Use cabinet cluster attach to
assign it to a new cluster, then cabinet restore to provision it there.
# Interactive
cod cabinet detach
# Scripted
cod cabinet detach my-cabinet \
--enterprise acme \
--environment prod \
--silent
Automation reference
Required flags (--silent mode): --enterprise, --environment; cabinet name as the first positional argument or via --cabinet
Preconditions: The cabinet definition must exist.
Idempotency: Safe to re-run — clears the cluster field regardless of its current value. Running on an already-unattached cabinet is a no-op.
State after: Unattached. Any infrastructure on the former cluster is untouched.
Move a cabinet to a different cluster
To move a running cabinet from one cluster to another:
# Step 1: Tear down the cabinet's infrastructure on the current cluster
cod cabinet destroy my-cabinet \
--enterprise acme --environment prod --silent
# Step 2: Clear the cluster assignment
cod cabinet detach my-cabinet \
--enterprise acme --environment prod --silent
# Step 3: Assign the cabinet to the new cluster
cod cabinet cluster attach my-cabinet \
--enterprise acme --environment prod \
--cluster new-cluster --silent
# Step 4: Provision the cabinet on the new cluster
cod cabinet restore \
--cabinet my-cabinet \
--enterprise acme --environment prod --silent
No cluster-level operations are required. The cabinet definition — including its full version history and configuration — moves intact.
What's next
- Cluster Workflows — define clusters, run
cluster restore, and attach cabinets - Manage assets — deploy assets into cabinets
- Manage snapshots — roll back a cabinet
- Manage environments — group cabinets by environment