CLI Reference

Container Use provides a comprehensive CLI for managing isolated development environments. All commands follow the pattern:

container-use {command} [options] [arguments]

Shorthand: The cu command is an alias for container-use and can be used interchangeably.

Global Options

These options can be used with any command:

--help, -h - Show help for a command
--version - Show version information
--debug - Enable debug output

Commands

`container-use list`

List all environments and their status.

container-use list

Options:

--no-trunc - Don’t truncate output
--quiet, -q - Only show environment IDs

Output example:

ID              TITLE                     CREATED       UPDATED
frontend-work   React UI Components       5 mins ago    1 min ago
backend-api     FastAPI User Service      3 mins ago    2 mins ago

`container-use log`

View the commit history and commands executed in an environment.

container-use log {environment-id}

Options:

--patch, -p - Show patch output with diffs

Example:

container-use log fancy-mallard
# Shows full history with commands and file changes

container-use log fancy-mallard --patch
# Shows history with patch diffs

`container-use diff`

Show the code changes made in an environment compared to its base branch.

container-use diff {environment-id}

Example:

container-use diff fancy-mallard
# Shows full diff output

`container-use checkout`

Check out an environment’s branch locally to explore in your IDE.

container-use checkout {environment-id}

Options:

--branch, -b - Specify branch name to checkout

Example:

container-use checkout fancy-mallard
# Switches to branch 'cu-fancy-mallard'

`container-use terminal`

Open an interactive terminal session inside the environment’s container.

container-use terminal {environment-id}

Example:

container-use terminal fancy-mallard
# Opens interactive shell in container

`container-use merge`

Merge an environment’s work into your current branch, preserving commit history.

container-use merge {environment-id}

Options:

--delete, -d - Delete environment after successful merge

Example:

git checkout main
container-use merge fancy-mallard
# Merges environment changes into current branch

`container-use apply`

Apply an environment’s changes as staged modifications without commits.

container-use apply {environment-id}

Options:

--delete, -d - Delete environment after successful apply

Example:

git checkout main
container-use apply fancy-mallard
# Stages all changes for you to commit

`container-use delete`

Delete an environment and clean up its resources.

container-use delete {environment-id}

Options:

--all - Delete all environments

Example:

container-use delete fancy-mallard
# Deletes the specified environment

container-use delete --all
# Deletes all environments

`container-use watch`

Monitor environment activity in real-time as agents work.

container-use watch

Example:

container-use watch
# Shows live updates from all active environments

`container-use config`

Manage default environment configurations.

container-use config {subcommand}

Configuration Management:

show [environment-id] - Display current configuration
import {environment-id} - Import configuration from an environment

Base Image:

base-image set {image} - Set default base image
base-image get - Show current base image
base-image reset - Reset to default base image

Setup Commands:

setup-command add {command} - Add setup command
setup-command remove {command} - Remove setup command
setup-command list - List setup commands
setup-command clear - Clear all setup commands

Install Commands:

install-command add {command} - Add install command
install-command remove {command} - Remove install command
install-command list - List install commands
install-command clear - Clear all install commands

Environment Variables:

env set {key} {value} - Set environment variable
env unset {key} - Unset environment variable
env list - List environment variables
env clear - Clear all environment variables

Secrets:

secret set {key} {value} - Set secret
secret unset {key} - Unset secret
secret list - List secrets
secret clear - Clear all secrets

Agent Integration:

agent [agent] - Configure MCP server for specific agent (claude, goose, cursor, etc.)

Example:

container-use config show
# Shows current configuration

container-use config base-image set python:3.11
# Sets Python 3.11 as default base image

container-use config setup-command add "pip install -r requirements.txt"
# Adds pip install as setup command

`container-use version`

Display Container Use version information.

container-use version

`container-use stdio`

Start Container Use as an MCP (Model Context Protocol) server for agent integration.

container-use stdio

Note: This command is typically used in agent configuration files, not run directly by users.

`container-use completion`

Generate shell completion scripts.

container-use completion {shell}

Supported shells: bash, zsh, fish, powershell Example:

container-use completion bash > /etc/bash_completion.d/container-use
# Installs bash completion

Environment IDs

Environment IDs are randomly generated two-word identifiers like fancy-mallard or clever-dolphin. You can use:

Full ID: fancy-mallard
Partial ID: fancy (if unique)
Branch name: cu-fancy-mallard

Exit Codes

0 - Success
1 - General error
2 - Command syntax error
3 - Environment not found
4 - Operation cancelled

Examples

Basic Workflow

# 1. List environments
container-use list

# 2. Review changes
container-use diff clever-dolphin

# 3. Check out locally
container-use checkout clever-dolphin

# 4. Accept work
container-use merge clever-dolphin

Debugging Workflow

# 1. See what agent did
container-use log problematic-env

# 2. Enter container to debug
container-use terminal problematic-env

# 3. Fix issues...

# 4. Apply changes
container-use apply problematic-env

Monitoring Workflow

# 1. Start watching
container-use watch

# 2. Agent works in background...

# 3. See specific environment
container-use log active-env

Get Started

Guides

Reference

Global Options

Commands

`container-use list`

`container-use log`

`container-use diff`

`container-use checkout`

`container-use terminal`

`container-use merge`

`container-use apply`

`container-use delete`

`container-use watch`

`container-use config`

`container-use version`

`container-use stdio`

`container-use completion`

Environment IDs

Exit Codes

Examples

Basic Workflow

Debugging Workflow

Monitoring Workflow

​Global Options

​Commands

​container-use list

​container-use log

​container-use diff

​container-use checkout

​container-use terminal

​container-use merge

​container-use apply

​container-use delete

​container-use watch

​container-use config

​container-use version

​container-use stdio

​container-use completion

​Environment IDs

​Exit Codes

​Examples

​Basic Workflow

​Debugging Workflow

​Monitoring Workflow

Global Options

Commands

`container-use list`

`container-use log`

`container-use diff`

`container-use checkout`

`container-use terminal`

`container-use merge`

`container-use apply`

`container-use delete`

`container-use watch`

`container-use config`

`container-use version`

`container-use stdio`

`container-use completion`

Environment IDs

Exit Codes

Examples

Basic Workflow

Debugging Workflow

Monitoring Workflow