CLI Reference

The cc-deck command-line tool manages the plugin, sessions, snapshots, and workspace builds.

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

Command Groups

Help output organizes commands into four groups by usage frequency.

Daily

attach, ls, exec. These commands are available both at the top level and under ws.

Session

snapshot

Workspace

ws (full lifecycle management)

Config

config (plugin, profile, domains, completion)

Build

build

Daily Commands

Three high-frequency workspace commands are available directly at the top level. They behave identically to their ws subcommand counterparts.

attach

Attach to a running workspace. For container workspaces, 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 attach mydev
cc-deck attach                        # resolves from project config
cc-deck attach --branch feature       # land in a specific worktree
Flag Description

--branch

Attach and land in a specific worktree directory inside the container

ls

List all workspaces with their current status.

cc-deck ls
cc-deck ls --type container
cc-deck ls --worktrees
cc-deck ls -o json
Flag Short Description

--type

-t

Filter by workspace type

--worktrees

-w

Show git worktrees within each project

exec

Run a command inside a container workspace.

cc-deck exec mydev -- ls /workspace
cc-deck exec mydev -- bash

Build 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 config plugin install
cc-deck config plugin install --layout minimal
cc-deck config plugin install --force
cc-deck config 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 config plugin status
cc-deck config plugin status -o json

plugin remove

Remove the plugin, layouts, and hooks.

cc-deck config plugin remove
cc-deck config 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

build

Unified setup lifecycle commands for provisioning container images and SSH hosts from a declarative manifest. The --target flag selects which provisioning targets to operate on. Valid targets are container, ssh, or both as container,ssh.

build init

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

cc-deck build init my-team-setup
cc-deck build init                    # defaults to .cc-deck/setup/
cc-deck build init my-team-setup --force
cc-deck build init --target container
cc-deck build init --target ssh
cc-deck build init --target container,ssh
Flag Description

--force, -f

Overwrite existing setup directory

--target

Provisioning targets to generate: container, ssh, or container,ssh (default: container)

build run

Execute pre-generated build artifacts directly from the CLI. Auto-detects whether to run a container build (via podman or docker) or SSH provisioning (via ansible-playbook) based on the artifacts present in the setup directory.

cc-deck build run
cc-deck build run .cc-deck/setup/
cc-deck build run --target container
cc-deck build run --target ssh
cc-deck build run --push
Flag Description

--target

Force target type: container or ssh (auto-detected if omitted)

--push

Push container image after successful build (container targets only, requires targets.container.registry in manifest)

Exit codes from the underlying build tool (podman, ansible-playbook) are passed through.

build verify

Smoke-test a provisioned target. For container targets, starts a container and checks tool availability, Claude Code startup, and cc-deck version. For SSH targets, connects to the remote host and validates installed tools. Reports pass/fail for each check.

cc-deck build verify my-team-setup --target container
cc-deck build verify my-team-setup --target ssh
Flag Description

--target

Target to verify: container or ssh (required)

build diff

Show manifest drift between the declared setup and the generated artifacts. When --target is omitted, auto-detects available targets in the setup directory.

cc-deck build diff my-team-setup
cc-deck build diff my-team-setup --target container
cc-deck build diff my-team-setup --target ssh
Flag Description

--target

Target to diff: container or ssh (auto-detected if omitted)

Reports tools, plugins, MCP servers, and other components that are in the manifest but not reflected in the generated provisioning artifacts.

profile

Manage credential profiles for AI backends.

profile add

Interactively create a new credential profile.

cc-deck config profile add myprofile

profile list

List all credential profiles.

cc-deck config profile list
cc-deck config profile list -o json

profile use

Set the default credential profile.

cc-deck config profile use myprofile

profile show

Show details of a credential profile.

cc-deck config profile show myprofile

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 config domains init
cc-deck config 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 config domains list

domains show

Display the expanded domain patterns for a specific group.

cc-deck config domains show python
cc-deck config 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 config domains blocked my-session
cc-deck config 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 config domains add my-session pypi.org
cc-deck config 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 config domains remove my-session pypi.org
cc-deck config domains remove my-session docker

Workspace Commands

ws

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

The commands attach, ls, and exec are also available at the top level (see Daily Commands).

ws new

Create a new workspace. 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 ws new                    # reads from .cc-deck/environment.yaml
cc-deck ws new mydev --type local
cc-deck ws new --type compose --image quay.io/cc-deck/cc-deck-demo:latest
cc-deck ws new --variant auth     # separate container instance
cc-deck ws new mydev --type container --port 8080:80
cc-deck ws new mydev --type ssh --host user@dev.example.com --repo https://github.com/org/repo.git
cc-deck ws new mydev --type ssh --repo https://github.com/org/repo.git --branch develop
Flag Short Description

--type

-t

Workspace type: local, container, compose, ssh, 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, k8s-deploy)

--mount

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

--auth

Auth mode: auto (default), none, api, vertex, bedrock (container, compose, ssh, k8s-deploy)

--allowed-domains

Domain groups for network filtering, repeatable (compose only)

--variant

Variant name for multiple container instances from the same definition

--host

SSH target host as user@hostname (ssh only)

--ssh-port

SSH port (ssh only, default: 22)

--identity-file

Path to SSH private key (ssh only)

--jump-host

SSH jump/bastion host (ssh only)

--ssh-config

Custom SSH config file path (ssh only)

--workspace

Remote workspace directory (ssh only, default: ~/workspace)

--global

Force resolution from global definition store (mutually exclusive with --local)

--local

Force resolution from project-local definition (mutually exclusive with --global)

--namespace

-n

Kubernetes namespace (k8s-deploy)

--kubeconfig

Path to kubeconfig file (k8s-deploy)

--context

Kubeconfig context name (k8s-deploy)

--storage-size

PVC storage size, e.g. 10Gi (k8s-deploy, default: 10Gi)

--storage-class

Kubernetes StorageClass name (k8s-deploy)

--existing-secret

Reference to pre-existing K8s Secret for credentials (k8s-deploy)

--secret-store

External Secrets Operator SecretStore type (k8s-deploy)

--secret-store-ref

External Secrets Operator SecretStore name (k8s-deploy)

--secret-path

External Secrets Operator secret path (k8s-deploy)

--build-dir

Build directory containing cc-deck-image.yaml for MCP sidecar generation (k8s-deploy)

--no-network-policy

Skip NetworkPolicy creation (k8s-deploy)

--allow-domain

Additional allowed domain for NetworkPolicy, repeatable (k8s-deploy)

--allow-group

Domain group for NetworkPolicy, repeatable (k8s-deploy)

--keep-volumes

Preserve PVCs when deleting (k8s-deploy)

--timeout

Pod readiness timeout, e.g. 5m (k8s-deploy, default: 5m)

--repo

Git repository URL to clone into workspace, repeatable (ssh, container, compose, k8s-deploy). When run inside a git repo, the current project is auto-detected and included.

--branch

Branch for the most recent --repo flag, repeatable. Requires a preceding --repo.

ws attach

Attach to a workspace. Creates a Zellij session with the cc-deck layout if no session exists, or reattaches to an existing session. For infrastructure-managed workspaces (container, compose, k8s-deploy), stopped infrastructure is auto-started before session creation. When no name is provided, resolves from workspace definitions in the central store.

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

--branch

Attach and land in a specific worktree directory inside the container

ws kill-session

Kill the Zellij session without affecting infrastructure. The underlying container or pod remains running. The next ws attach creates a fresh session with the cc-deck layout. Works with all workspace types.

cc-deck ws kill-session mydev
cc-deck ws kill-session              # resolves from workspace definitions

ws delete

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

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

--force

-f

Force delete a running workspace

--keep-volumes

Preserve data volumes when deleting container workspaces

ws list

List all workspaces with their current status. Shows both global and project-local workspaces in a unified view. Each entry includes a SOURCE column indicating the definition origin (global, project, or empty for orphan instances).

cc-deck ws list
cc-deck ws ls                        # alias
cc-deck ws list --type container
cc-deck ws list --worktrees
cc-deck ws list -o json
Flag Short Description

--type

-t

Filter by workspace type

--worktrees

-w

Show git worktrees within each project

ws status

Display detailed status information for a workspace. For project-local workspaces, the output includes the project directory path.

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

ws start

Start infrastructure for a stopped workspace. Only applies to workspace types that manage infrastructure (container, compose, k8s-deploy). For local and SSH workspaces, prints a suggestion to use ws attach instead. Does not create a Zellij session; use ws attach after starting.

cc-deck ws start mydev
cc-deck ws start                     # resolves from workspace definitions

ws stop

Stop infrastructure and kill the Zellij session. Only applies to workspace types that manage infrastructure (container, compose, k8s-deploy). For local and SSH workspaces, prints a suggestion to use ws kill-session instead. The session is killed first, then the infrastructure is stopped.

cc-deck ws stop mydev
cc-deck ws stop                      # resolves from workspace definitions

ws logs

View workspace logs.

cc-deck ws logs mydev

ws refresh-creds

Push fresh credentials to a remote SSH workspace without attaching. This is useful for keeping long-running sessions alive when local credentials rotate. Only applicable to SSH workspaces.

cc-deck ws refresh-creds remote-dev
cc-deck ws refresh-creds             # resolves from project config

ws prune

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

cc-deck ws prune

ws exec

Run a command inside a container workspace.

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

ws push

Copy local files into a workspace. Works with all workspace types: local (filesystem copy), container (podman cp), SSH (rsync), and Kubernetes (tar-over-exec).

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

ws pull

Copy files from a workspace to the local machine. Works with all workspace types: local (filesystem copy), container (podman cp), SSH (rsync), and Kubernetes (tar-over-exec).

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

ws harvest

Fetch git commits from a remote workspace into the local repository. Works with SSH, Kubernetes, container, and compose workspace types.

cc-deck ws harvest mydev
cc-deck ws harvest mydev --branch feature-x
cc-deck ws harvest mydev --branch feature-x --create-pr
Flag Description

--branch

Create a local branch with this name from fetched commits

--create-pr

Push branch and create a GitHub pull request

ws voice

Start voice relay for hands-free dictation into a workspace’s attended agent session. Captures audio from the local microphone, transcribes locally via whisper.cpp, and relays text into the attended pane. Uses voice activity detection (VAD) with mute/unmute toggle.

When connected, a ♫ indicator appears in the sidebar header (bright green when listening, dim when muted). Mute can be toggled from the sidebar (Alt+m, m in navigation mode, or clicking ♫) or from the voice TUI (m).

cc-deck ws voice mydev
cc-deck ws voice mydev --model small.en --verbose
cc-deck ws voice --setup
cc-deck ws voice --list-devices
Flag Description

--model

Whisper model name: tiny.en, base.en (default), small.en, medium

--port

Whisper-server port (default: 8234)

--threshold

VAD sensitivity (0-100, logarithmic scale). Overrides the config file value.

--verbose

Enable detailed logging to ~/.local/state/cc-deck/voice.log

--setup

Check dependencies and download the whisper model

--list-devices

List available audio input devices and exit

ws pipe

Send a raw payload to a named Zellij pipe in a workspace. Useful for scripting and diagnostics.

cc-deck ws pipe mydev --name cc-deck:voice --payload "hello world"
Flag Description

--name

Pipe name to send to (required)

--payload

Text payload to deliver

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.