CLI Reference

The cc-deck command-line tool manages the plugin, sessions, snapshots, and container images.

Global Flags

Flag Short Description

--config

Config file path (default: $XDG_CONFIG_HOME/cc-deck/config.yaml)

--kubeconfig

Path to kubeconfig (default: $KUBECONFIG or ~/.kube/config)

--namespace

-n

Target Kubernetes namespace

--output

-o

Output format: text (default), json, yaml

--profile

-p

Credential profile to use

--verbose

-v

Verbose output

Commands

version

Print version information.

cc-deck version
cc-deck version -o json

plugin

Manage the Zellij plugin installation.

plugin install

Install the WASM plugin, layouts, and Claude Code hooks.

cc-deck plugin install
cc-deck plugin install --layout minimal
cc-deck plugin install --force
cc-deck plugin install --install-zellij
Flag Description

--force, -f

Overwrite without prompting

--skip-backup

Skip creating backup of settings.json

--layout

Default layout variant: standard (default), minimal, clean

--install-zellij

Download and install matching Zellij binary

plugin status

Show current installation status.

cc-deck plugin status
cc-deck plugin status -o json

plugin remove

Remove the plugin, layouts, and hooks.

cc-deck plugin remove
cc-deck plugin remove --skip-backup

snapshot

Manage session state snapshots.

snapshot save

Save current session state.

cc-deck snapshot save my-checkpoint
cc-deck snapshot save --auto   # sequential naming

snapshot restore

Restore a saved snapshot.

cc-deck snapshot restore my-checkpoint

snapshot list

List all saved snapshots.

cc-deck snapshot list
cc-deck snapshot list -o json

snapshot remove

Delete a snapshot.

cc-deck snapshot remove my-checkpoint

image

Container image lifecycle commands.

image init

Scaffold a build directory with manifest and AI commands. When no directory is specified and the project has .cc-deck/, defaults to .cc-deck/image/.

cc-deck image init my-team-image
cc-deck image init                    # defaults to .cc-deck/image/
cc-deck image init my-team-image --force
Flag Description

--force, -f

Overwrite existing build directory

image verify

Smoke-test a built container image.

cc-deck image verify my-team-image

Starts a container, checks tool availability, Claude Code startup, and cc-deck version. Reports pass/fail for each check.

image diff

Compare manifest against generated Containerfile.

cc-deck image diff my-team-image

Reports tools, plugins, MCP servers, and GitHub tools that are in the manifest but not reflected in the Containerfile.

deploy (compose mode)

When the --compose flag is provided, the deploy command generates Podman compose files instead of deploying to Kubernetes. This mode reads the manifest from the specified build directory and produces a compose.yaml, .env.example, and optional proxy sidecar configuration.

cc-deck deploy my-session --compose ./my-team-image
cc-deck deploy my-session --compose ./my-team-image --output-dir ./output
cc-deck deploy my-session --compose ./my-team-image --allowed-domains "+rust,-docker"
cc-deck deploy my-session --compose ./my-team-image --allowed-domains "all"
Flag Description

--compose <build-dir>

Generate Podman compose files from a build directory (reads cc-deck-build.yaml manifest)

--output-dir <dir>

Output directory for generated compose files (default: same as build directory)

--allowed-domains <spec>

Domain override for network filtering (see below)

The --allowed-domains flag accepts several formats:

Format Behavior

+group

Add a group to the manifest defaults (e.g., +rust)

-group

Remove a group from the manifest defaults (e.g., -docker)

group,group

Replace manifest defaults entirely with the listed groups

all

Disable network filtering completely (all outbound traffic is allowed)

Multiple additions and removals can be combined with commas (e.g., +rust,-docker,+gitlab). If neither anthropic nor vertexai is present in the final domain list, the anthropic group is injected automatically.

domains

Manage domain groups for network filtering in containerized sessions. Domain groups are named collections of domain patterns (e.g., python includes pypi.org and related hosts). Groups can be built-in, user-defined, or extended from built-in definitions.

domains init

Seed ~/.config/cc-deck/domains.yaml with commented built-in group definitions as a starting point for customization.

cc-deck domains init
cc-deck domains init --force
Flag Description

--force

Overwrite existing domains.yaml file

domains list

List all available domain groups with their source and domain count. Sources include builtin (shipped with cc-deck), user (defined in domains.yaml), and extended (user config that extends a built-in group).

cc-deck domains list

domains show

Display the expanded domain patterns for a specific group.

cc-deck domains show python
cc-deck domains show github

domains blocked

Show blocked requests from the tinyproxy logs of a running Podman session. This command requires Podman and a session deployed with network filtering enabled.

cc-deck domains blocked my-session
cc-deck domains blocked my-session --since 30m
Flag Description

--since

Show blocks from the last duration (default: 1h)

domains add

Add a domain or domain group to a running Podman session. The proxy container is restarted to apply the change.

cc-deck domains add my-session pypi.org
cc-deck domains add my-session rust

domains remove

Remove a domain or domain group from a running Podman session. The proxy container is restarted to apply the change.

cc-deck domains remove my-session pypi.org
cc-deck domains remove my-session docker

env

Manage environments across all supported backends (local, container, Kubernetes). When run inside a project with .cc-deck/environment.yaml, environment names are resolved automatically.

env create

Create a new environment. When run inside a project with .cc-deck/environment.yaml, name and settings are read from the definition. In a git repository without a definition, one is scaffolded from CLI flags before provisioning.

cc-deck env create                    # reads from .cc-deck/environment.yaml
cc-deck env create mydev --type local
cc-deck env create --type compose --image quay.io/cc-deck/cc-deck-demo:latest
cc-deck env create --variant auth     # separate container instance
cc-deck env create mydev --type container --port 8080:80
Flag Short Description

--type

-t

Environment type: local, container, compose, k8s-deploy, k8s-sandbox

--image

Container image to use (container, compose)

--port

-p

Port mapping (host:container), repeatable (container, compose)

--all-ports

Expose all container ports (container)

--storage

Storage type: named-volume (container default), host-path (compose default)

--path

Project directory (compose: defaults to cwd)

--credential

Credential as KEY=VALUE, repeatable (container, compose)

--mount

Bind mount as src:dst[:ro], repeatable (container, compose)

--auth

Auth mode: auto (default), none, api, vertex, bedrock (container, compose)

--allowed-domains

Domain groups for network filtering, repeatable (compose only)

--variant

Variant name for multiple container instances from the same definition

env attach

Attach to a running environment. For container environments, this opens a Zellij session inside the container. Stopped containers are auto-started before attaching. When no name is provided, resolves from .cc-deck/environment.yaml in the project.

cc-deck env attach mydev
cc-deck env attach                    # resolves from project config
cc-deck env attach --branch feature   # land in a specific worktree
Flag Short Description

--branch

Attach and land in a specific worktree directory inside the container

env delete

Delete an environment and its resources. For project-local environments, removes runtime state (status.yaml, run/) but preserves the committed definition (environment.yaml).

cc-deck env delete mydev
cc-deck env delete                    # resolves from project config
cc-deck env delete --force --keep-volumes
Flag Short Description

--force

-f

Force delete a running environment

--keep-volumes

Preserve data volumes when deleting container environments

env list

List all environments with their current status. Shows both global and project-local environments in a unified view. Projects registered in the global registry are included with their paths.

cc-deck env list
cc-deck env list --type container
cc-deck env list --worktrees
cc-deck env list -o json
Flag Short Description

--type

-t

Filter by environment type

--worktrees

-w

Show git worktrees within each project

env status

Display detailed status information for an environment.

cc-deck env status mydev
cc-deck env status                    # resolves from project config
cc-deck env status -o json

env start

Start a stopped environment.

cc-deck env start mydev
cc-deck env start                     # resolves from project config

env stop

Gracefully stop a running environment.

cc-deck env stop mydev
cc-deck env stop                      # resolves from project config

env prune

Remove stale entries from the global project registry. Entries whose directories no longer exist are removed.

cc-deck env prune

env exec

Run a command inside a container environment.

cc-deck env exec mydev -- ls /workspace
cc-deck env exec mydev -- npm install

env push

Copy local files into a container environment.

cc-deck env push mydev ./src /workspace/src
cc-deck env push mydev ./config.yaml

env pull

Copy files from a container environment to the local machine.

cc-deck env pull mydev /workspace/output ./output
cc-deck env pull mydev /workspace/results

env harvest

Extract work products from an environment. Not supported for container environments (use push/pull instead).

cc-deck env harvest mydev

hook

Internal command used by Claude Code hooks. Not intended for direct use.

cc-deck hook --pane-id "$ZELLIJ_PANE_ID"

Forwards Claude Code session events to the sidebar plugin.