Skip to content

CLI_REFERENCE.md

Latest commit

 

History

History
713 lines (504 loc) · 21.9 KB

CLI_REFERENCE.md

File metadata and controls

713 lines (504 loc) · 21.9 KB

Claude Code with Bedrock - CLI Reference

This document provides a complete reference for all ccwb (Claude Code with Bedrock) commands.

Table of Contents

Overview

The Claude Code with Bedrock CLI (ccwb) provides commands for IT administrators to:

  • Configure OIDC authentication
  • Deploy AWS infrastructure
  • Create distribution packages
  • Manage deployments

Installation

# Clone the repository
git clone [<repository-url>](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock.git)
cd guidance-for-claude-code-with-amazon-bedrock/source

# Install dependencies
poetry install

# Run commands with poetry
poetry run ccwb <command>

Command Reference

init - Configure Deployment

Creates or updates the configuration for your Claude Code deployment.

poetry run ccwb init [options]

Options:

  • --profile <name> - Configuration profile name (default: "default")

What it does:

  • Checks prerequisites (AWS CLI, credentials, Python version)
  • Prompts for OIDC provider configuration
  • Prompts for authentication method selection:
    • Direct IAM: Uses IAM OIDC Provider for federation
    • Cognito: Uses Cognito Identity Pool for federation
  • Configures AWS settings (region, stack names)
  • Prompts for Claude model selection (Opus, Sonnet, Haiku)
  • Configures cross-region inference profiles (US, Europe, APAC)
  • Prompts for source region selection for model inference
  • Sets up monitoring options
  • Prompts for Windows build support via AWS CodeBuild (optional)
  • Saves configuration to .ccwb-config/config.json in the project directory

Note: This command only creates configuration. Use deploy to create AWS resources.

deploy - Deploy Infrastructure

Deploys CloudFormation stacks for authentication and monitoring.

poetry run ccwb deploy [stack] [options]

Arguments:

  • stack - Specific stack to deploy: auth, networking, monitoring, dashboard, analytics, or quota (optional)

Options:

  • --profile <name> - Configuration profile to use (default: "default")
  • --dry-run - Show what would be deployed without executing
  • --show-commands - Display AWS CLI commands instead of executing

What it does:

  • Deploys authentication infrastructure (IAM OIDC Provider or Cognito Identity Pool)
  • Creates IAM roles and policies for Bedrock access
  • Deploys monitoring infrastructure (if enabled)
  • Shows stack outputs including authentication resource identifiers

Stacks deployed:

  1. auth - Authentication infrastructure and IAM roles (always required)
  2. networking - VPC and networking resources for monitoring (optional)
  3. monitoring - OpenTelemetry collector on ECS Fargate (optional)
  4. dashboard - CloudWatch dashboard for usage metrics (optional)
  5. analytics - Kinesis Firehose and Athena for analytics (optional)
  6. quota - Per-user token quota monitoring and alerts (optional, requires dashboard)
  7. codebuild - AWS CodeBuild for Windows binary builds (optional, only if enabled during init)

Examples:

# Deploy all configured stacks
poetry run ccwb deploy

# Deploy only authentication
poetry run ccwb deploy auth

# Deploy quota monitoring (requires dashboard stack first)
poetry run ccwb deploy quota

# Show commands without executing
poetry run ccwb deploy --show-commands

# Dry run to see what would be deployed
poetry run ccwb deploy --dry-run

Note: Quota monitoring requires the dashboard stack to be deployed first. See Quota Monitoring Guide for detailed information.

test - Test Package

Tests the packaged distribution as an end user would experience it.

poetry run ccwb test [options]

Options:

  • --profile <name> - AWS profile to test (default: "ClaudeCode")
  • --quick - Run quick tests only
  • --api - Test actual Bedrock API calls (costs ~$0.001)

What it does:

  • Simulates package installation in temporary directory
  • Runs the installer script
  • Verifies AWS profile configuration
  • Tests authentication and IAM role assumption
  • Checks Bedrock access in configured regions
  • Optionally tests actual API calls to Claude models

Note: This command actually installs the package to properly test it.

package - Create Distribution

Creates a distribution package for end users.

poetry run ccwb package [options]

Options:

  • --target-platform <platform> - Target platform for binary (default: "all")
    • macos - Build for current macOS architecture
    • macos-arm64 - Build for Apple Silicon Macs
    • macos-intel - Build for Intel Macs (uses Rosetta on ARM Macs)
    • linux - Build for Linux (native, current architecture)
    • linux-x64 - Build for Linux x64 using Docker
    • linux-arm64 - Build for Linux ARM64 using Docker
    • windows - Build for Windows (uses CodeBuild - requires enabling during init)
    • all - Build for all available platforms
  • --distribute - Upload package and generate distribution URL
  • --expires-hours <hours> - Distribution URL expiration in hours (with --distribute) [default: "48"]
  • --profile <name> - Configuration profile to use [default: "default"]

What it does:

  • Builds Nuitka executable from authentication code
  • Creates configuration file with:
    • OIDC provider settings
    • Identity Pool ID from deployed stack
    • Credential storage method (keyring or session)
    • Selected Claude model and cross-region profile
    • Source region for model inference
  • Generates installer script (install.sh for Unix, install.bat for Windows)
  • Creates user documentation
  • Optionally uploads to S3 and generates presigned URL (with --distribute)

Platform Support (Hybrid Build System):

  • macOS: Uses PyInstaller with architecture-specific builds
    • ARM64: Native build on Apple Silicon Macs (works on all Macs)
    • Intel: Optional - requires x86_64 Python environment on ARM Macs
    • Universal: Requires both architectures' Python libraries (not currently automated)
  • Linux: Uses PyInstaller in Docker containers
    • x64: Uses linux/amd64 Docker platform
    • ARM64: Uses linux/arm64 Docker platform
    • Docker Desktop handles architecture emulation automatically
  • Windows: Uses Nuitka via AWS CodeBuild (if enabled during init)
    • Automated builds take 12-15 minutes
    • Requires CodeBuild to be enabled during init
    • Will be skipped if CodeBuild is not enabled

Intel Mac Build Setup (Optional):

To enable Intel builds on Apple Silicon Macs (optional):

# Step 1: Install x86_64 Homebrew (if not already installed)
arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Step 2: Install x86_64 Python
arch -x86_64 /usr/local/bin/brew install python@3.12

# Step 3: Create x86_64 virtual environment
arch -x86_64 /usr/local/bin/python3.12 -m venv ~/venv-x86

# Step 4: Install required packages
arch -x86_64 ~/venv-x86/bin/pip install pyinstaller boto3 keyring

Behavior when Intel environment is not set up:

  • For --target-platform=all: Skips Intel builds with a note, builds all other platforms
  • For --target-platform=macos-intel: Shows instructions for optional setup, skips the build
  • The package process continues successfully without Intel binaries
  • ARM64 binaries can be distributed to all Mac users (Intel and Apple Silicon)

Graceful Fallback Behavior:

The package command is designed to handle missing optional components gracefully:

  • Intel Mac builds: Skipped if x86_64 Python environment is not available on ARM Macs
  • Windows builds: Skipped if CodeBuild was not enabled during init
  • Linux builds: Skipped if Docker is not available
  • At least one platform must build successfully for the package command to succeed

This ensures that packaging always works, even if some optional platforms are not available.

Output files:

  • credential-process-<platform> - Authentication executable
    • credential-process-macos-arm64 - macOS Apple Silicon
    • credential-process-macos-intel - macOS Intel
    • credential-process-linux-x64 - Linux x64
    • credential-process-linux-arm64 - Linux ARM64
    • credential-process-windows.exe - Windows x64
  • otel-helper-<platform> - OTEL helper (if monitoring enabled)
  • config.json - Configuration
  • install.sh - Unix installer script (auto-detects architecture)
  • install.bat - Windows installer script
  • README.md - Installation instructions
  • Includes Claude Code telemetry settings (if monitoring enabled)
  • Configures environment variables for model selection (ANTHROPIC_MODEL, ANTHROPIC_SMALL_FAST_MODEL)

Output structure:

dist/
├── credential-process-macos-arm64     # macOS ARM64 executable
├── credential-process-macos-intel     # macOS Intel executable
├── credential-process-linux-x64       # Linux x64 executable
├── credential-process-linux-arm64     # Linux ARM64 executable
├── credential-process-windows.exe     # Windows x64 executable
├── otel-helper-macos-arm64           # macOS ARM64 OTEL helper
├── otel-helper-macos-intel           # macOS Intel OTEL helper
├── otel-helper-linux-x64             # Linux x64 OTEL helper
├── otel-helper-linux-arm64           # Linux ARM64 OTEL helper
├── otel-helper-windows.exe           # Windows OTEL helper
├── config.json                       # Configuration
├── install.sh                        # Unix installer (auto-detects architecture)
├── install.bat                       # Windows installer
├── README.md                         # User instructions
└── .claude/
    └── settings.json                 # Telemetry settings (optional)

builds - List and Manage CodeBuild Builds

Shows recent Windows binary builds and their status.

poetry run ccwb builds [options]

Options:

  • --limit <n> - Number of builds to show (default: "10")
  • --project <name> - CodeBuild project name (default: auto-detect)
  • --status <id> - Check status of a specific build by ID

What it does:

  • Lists recent CodeBuild builds for Windows binaries
  • Shows build status, duration, and completion time
  • Provides console links to view full build logs
  • Monitors in-progress builds

Note: This command requires CodeBuild to be enabled during the init process. If CodeBuild was not enabled, you'll need to re-run init and enable Windows build support.

Example output:

Recent Windows Builds

| Build ID | Status | Started | Duration |
|----------|--------|---------|----------|
| project:abc123 | SUCCEEDED | 2024-08-26 10:15 | 12m 34s |
| project:def456 | IN_PROGRESS | 2024-08-26 10:30 | - |

distribute - Share Packages via Distribution

Upload and distribute built packages via presigned S3 URLs or authenticated landing page.

poetry run ccwb distribute [options]

Options:

  • --expires-hours <hours> - URL expiration time in hours (1-168) [default: "48"]
  • --get-latest - Retrieve the latest distribution URL (presigned-s3 only)
  • --profile <name> - Configuration profile to use [default: "default"]
  • --package-path <path> - Path to package directory [default: "dist"]
  • --build-profile <name> - Select build by profile name
  • --timestamp <timestamp> - Select build by timestamp (format: YYYY-MM-DD-HHMMSS)
  • --latest - Auto-select latest build without wizard
  • --allowed-ips <ranges> - Comma-separated IP ranges for access control (presigned-s3 only)
  • --show-qr - Display QR code for URL (requires qrcode library)

What it does:

Behavior depends on your configured distribution type:

Presigned S3 URLs (Simple):

  • Uploads packages to S3 bucket
  • Generates secure presigned URLs (default 48 hours)
  • Stores URLs in Parameter Store for team access
  • Share URLs via email/Slack
  • No authentication required for downloads

Landing Page (Enterprise):

  • Uploads platform-specific packages (windows/linux/mac/all-platforms)
  • Updates S3 metadata (profile, timestamp, release date)
  • Provides landing page URL for authenticated access
  • Users authenticate via IdP (Okta/Azure/Auth0/Cognito)
  • Platform auto-detection and recommendations

Distribution workflow:

  1. Build packages: poetry run ccwb package
  2. Upload and distribute: poetry run ccwb distribute
  3. Presigned-s3: Share generated URLs with developers
  4. Landing-page: Direct users to your landing page URL

Examples:

# Distribute latest build (interactive build selection)
poetry run ccwb distribute

# Distribute latest build automatically (skip wizard)
poetry run ccwb distribute --latest

# Distribute specific build by timestamp
poetry run ccwb distribute --timestamp 2024-11-14-083022

# Distribute with custom expiration (presigned-s3 only)
poetry run ccwb distribute --expires-hours=72

# Get existing URL without re-uploading (presigned-s3 only)
poetry run ccwb distribute --get-latest

# Distribute with QR code for mobile sharing
poetry run ccwb distribute --show-qr

Build Selection:

If you have multiple builds in dist/, the command will:

  1. Scan for organized profile/timestamp builds
  2. Show interactive wizard to select which build to distribute
  3. Display build date, size, and platforms included
  4. Allow selection by profile name or timestamp

Use --latest to skip the wizard and auto-select the most recent build.

Platform-Specific Uploads (Landing Page):

For landing-page distribution, packages are organized by platform:

  • packages/windows/latest.zip - Windows package
  • packages/linux/latest.zip - Linux package
  • packages/mac/latest.zip - macOS package
  • packages/all-platforms/latest.zip - All platforms bundle

Landing page auto-detects user's OS and recommends appropriate package.

status - Check Deployment Status

Shows the current deployment status and configuration.

poetry run ccwb status [options]

Options:

  • --profile <name> - Profile to check (default: "default")
  • --json - Output in JSON format
  • --detailed - Show detailed information

What it does:

  • Shows current configuration including:
    • Configuration profile and AWS profile names
    • OIDC provider and client ID
    • Selected Claude model and cross-region profile
    • Source region for model inference
    • Analytics and monitoring status
  • Checks CloudFormation stack status
  • Displays Identity Pool information
  • Shows monitoring configuration and endpoints

cleanup - Remove Installed Components

Removes components installed by the test command or manual installation.

poetry run ccwb cleanup [options]

Options:

  • --force - Skip confirmation prompts
  • --profile <name> - AWS profile name to remove (default: "ClaudeCode")

What it does:

  • Removes ~/claude-code-with-bedrock/ directory
  • Removes AWS profile from ~/.aws/config
  • Removes Claude settings from ~/.claude/settings.json
  • Shows what will be removed before taking action

Use this to:

  • Clean up after testing
  • Remove failed installations
  • Start fresh with a new configuration

Profile Management

The following commands manage multiple deployment profiles (v2.0+). Profiles let you manage configurations for different AWS accounts, regions, or organizations from a single machine.

context list - List All Profiles

Shows all available profiles with an indicator for the active profile.

poetry run ccwb context list

What it does:

  • Lists all profiles in ~/.ccwb/profiles/
  • Displays profile name, AWS region, and stack name
  • Highlights the currently active profile
  • Shows profile count

Example output:

Available Profiles:
  * production (us-east-1, stack: claude-code-prod)
    development (us-west-2, stack: claude-code-dev)
    eu-deployment (eu-west-1, stack: claude-code-eu)

Active profile: production
Total profiles: 3

context current - Show Active Profile

Displays the currently active profile name.

poetry run ccwb context current

What it does:

  • Shows the name of the active profile
  • Exits with error if no active profile is set

Example output:

Current profile: production

context use - Switch Active Profile

Changes the active profile to the specified one.

poetry run ccwb context use <profile-name>

Arguments:

  • profile-name - Name of the profile to activate (required)

What it does:

  • Sets the specified profile as active
  • Validates that the profile exists
  • Updates global configuration file

Examples:

# Switch to production profile
poetry run ccwb context use production

# Switch to development profile
poetry run ccwb context use development

context show - Display Profile Details

Shows detailed configuration for a profile.

poetry run ccwb context show [profile-name]

Arguments:

  • profile-name - Profile to display (optional, defaults to active profile)

Options:

  • --json - Output in JSON format

What it does:

  • Displays full profile configuration including:
    • AWS region and account
    • OIDC provider settings
    • Stack names
    • Model selection
    • Monitoring configuration
  • Masks sensitive values (client secrets)

Examples:

# Show active profile details
poetry run ccwb context show

# Show specific profile
poetry run ccwb context show production

# Output as JSON
poetry run ccwb context show --json

config validate - Validate Profile Configuration

Validates profile configuration for errors.

poetry run ccwb config validate [profile-name|all]

Arguments:

  • profile-name - Profile to validate (optional, defaults to active profile)
  • all - Validate all profiles

What it does:

  • Checks required fields are present
  • Validates field formats (region, stack names, URLs)
  • Verifies AWS credentials exist
  • Reports validation errors with suggestions

Examples:

# Validate active profile
poetry run ccwb config validate

# Validate specific profile
poetry run ccwb config validate production

# Validate all profiles
poetry run ccwb config validate all

config export - Export Profile Configuration

Exports a profile configuration to a file (sanitized).

poetry run ccwb config export [profile-name] [options]

Arguments:

  • profile-name - Profile to export (optional, defaults to active profile)

Options:

  • --output <file> - Output file path (default: <profile-name>.json)
  • --include-secrets - Include sensitive values (not recommended)

What it does:

  • Exports profile configuration to JSON file
  • Removes sensitive values by default (client secrets)
  • Creates portable configuration file

Examples:

# Export active profile (secrets removed)
poetry run ccwb config export

# Export specific profile to custom path
poetry run ccwb config export production --output prod-config.json

# Export with secrets (use caution)
poetry run ccwb config export --include-secrets

config import - Import Profile Configuration

Imports a profile configuration from a file.

poetry run ccwb config import <file> [name]

Arguments:

  • file - Path to configuration file (required)
  • name - Name for imported profile (optional, uses name from file)

Options:

  • --overwrite - Overwrite if profile already exists
  • --set-active - Set as active profile after import

What it does:

  • Imports profile configuration from JSON file
  • Validates configuration before importing
  • Creates new profile in ~/.ccwb/profiles/
  • Optionally sets as active profile

Examples:

# Import profile with default name
poetry run ccwb config import prod-config.json

# Import with custom name
poetry run ccwb config import config.json staging

# Import and set as active
poetry run ccwb config import config.json --set-active

# Overwrite existing profile
poetry run ccwb config import config.json production --overwrite

destroy - Remove Infrastructure

Removes deployed AWS infrastructure.

poetry run ccwb destroy [stack] [options]

Arguments:

  • stack - Specific stack to destroy: auth, networking, monitoring, dashboard, or analytics (optional)

Options:

  • --profile <name> - Configuration profile to use (default: "default")
  • --force - Skip confirmation prompts

What it does:

  • Deletes CloudFormation stacks in reverse order (analytics → dashboard → monitoring → networking → auth)
  • Shows resources to be deleted before proceeding
  • Warns about manual cleanup requirements (e.g., CloudWatch LogGroups)

Note: Some resources like CloudWatch LogGroups may require manual deletion.