Getting Started¶

Get charcoal-cli up and running in minutes.

Prerequisites¶

• Docker Engine 20.10+
• Dev Container CLI — Install via npm:

  npm install -g @devcontainers/cli
  

• Python 3.9 or higher

Install¶

# Run the install script
./install.sh

# Ensure ~/.local/bin is in your PATH
export PATH="$HOME/.local/bin:$PATH"

See the Install guide for detailed instructions, including local (no-install) usage.

Authenticate (Optional for Accessing Compute and Workflows )¶

While local workspaces work without authentication, cloud features (VM management, compute, billing) require logging in:

# Login with username/password + OTP
charcoal auth login

# Or use Google OAuth
charcoal auth login --method google

# Check your status
charcoal auth status

See the Auth Commands reference for details.

Launch Your First Workspace¶

charcoal up --ide https://github.com/octocat/hello-world.git

This clones the repo, builds a dev container, and opens VS Code in your browser at http://localhost:3000. Press Ctrl+C to stop.

Next Steps¶

• Learn how to list and manage workspaces
• Explore the full command reference
• Customize your setup with configuration options
• Understand dev containers and workspace concepts