@codivstack/cli

Official command-line interface for CodivStack - Self-hosted BYOC sandbox platform on AWS ECS Fargate.

Installation

# Global installation
npm install -g @codivstack/cli

# Or use with npx (no installation required)
npx @codivstack/cli <command>

Authentication

Set your API key as an environment variable:

export CS_API_KEY=your-api-key

# Alternative variable name
export CODIVSTACK_API_KEY=your-api-key

Get your API key from: https://codivstack.dev/dashboard

Optional: Custom API URL

export CODIVSTACK_API_URL=https://api.your-domain.com

Commands

Sandbox Management

List Sandboxes

codivstack sandbox list [options]

# Aliases
codivstack sb ls
codivstack sandbox ls

| Option | Description | |--------|-------------| | -s, --status <status> | Filter by status: running, stopped, all (default: all) | | --json | Output in JSON format |

Examples:

# List all sandboxes
codivstack sandbox list

# List only running sandboxes
codivstack sandbox list --status running

# Get JSON output for scripting
codivstack sandbox list --json

Create Sandbox

codivstack sandbox create [options]

| Option | Description | |--------|-------------| | -n, --name <name> | Sandbox name (auto-generated if not provided) | | -s, --size <size> | Sandbox size (default: nano) | | -t, --timeout <minutes> | Max runtime in minutes | | -w, --workspace <id> | Workspace ID to restore from | | --json | Output in JSON format |

Available Sizes:

• nano - 0.25 vCPU, 0.5 GB RAM
• tiny - 0.25 vCPU, 1 GB RAM
• small - 0.5 vCPU, 1 GB RAM
• basic - 0.5 vCPU, 2 GB RAM
• standard - 1 vCPU, 2 GB RAM
• medium - 1 vCPU, 4 GB RAM
• large - 2 vCPU, 4 GB RAM
• xlarge - 2 vCPU, 8 GB RAM
• xxlarge - 4 vCPU, 8 GB RAM
• huge - 4 vCPU, 16 GB RAM
• massive - 8 vCPU, 32 GB RAM

Examples:

# Create a nano sandbox (default)
codivstack sandbox create

# Create with specific size
codivstack sandbox create --size medium

# Create with name and timeout
codivstack sandbox create --name my-project --size large --timeout 60

# Create from existing workspace
codivstack sandbox create --workspace abc123-uuid --size small

Start Sandbox

codivstack sandbox start <sandboxId> [options]

| Option | Description | |--------|-------------| | -t, --timeout <minutes> | Max runtime in minutes (optional) | | --json | Output in JSON format |

Examples:

# Start a stopped sandbox
codivstack sandbox start sandbox-abc123

# Start with custom timeout
codivstack sandbox start sandbox-abc123 --timeout 120

Stop Sandbox

codivstack sandbox stop <sandboxId> [options]

| Option | Description | |--------|-------------| | --json | Output in JSON format |

Examples:

codivstack sandbox stop sandbox-abc123

Get Sandbox Status

codivstack sandbox status <sandboxId> [options]

# Alias
codivstack sandbox info <sandboxId>

| Option | Description | |--------|-------------| | --json | Output in JSON format |

Examples:

codivstack sandbox status sandbox-abc123
codivstack sandbox info sandbox-abc123 --json

Delete Sandbox

codivstack sandbox delete <sandboxId> [options]

# Alias
codivstack sandbox rm <sandboxId>

| Option | Description | |--------|-------------| | -f, --force | Force delete without confirmation | | --json | Output in JSON format |

Examples:

codivstack sandbox delete sandbox-abc123
codivstack sandbox rm sandbox-abc123 --force

Get Sandbox Metrics

codivstack sandbox metrics <sandboxId> [options]

| Option | Description | |--------|-------------| | --json | Output in JSON format |

Examples:

codivstack sandbox metrics sandbox-abc123

File Management

List Files

codivstack files list <sandboxId> [path] [options]

# Alias
codivstack fs ls <sandboxId> [path]

| Option | Description | |--------|-------------| | --json | Output in JSON format |

Examples:

# List root directory
codivstack files list sandbox-abc123

# List specific directory
codivstack files list sandbox-abc123 /src

# JSON output
codivstack files list sandbox-abc123 /src --json

Read File

codivstack files read <sandboxId> <path> [options]

# Alias
codivstack fs cat <sandboxId> <path>

| Option | Description | |--------|-------------| | -o, --output <file> | Save content to local file | | --json | Output in JSON format |

Examples:

# Print file content
codivstack files read sandbox-abc123 /app.js

# Save to local file
codivstack files read sandbox-abc123 /config.json --output ./local-config.json

Write File

codivstack files write <sandboxId> <path> [content] [options]

| Option | Description | |--------|-------------| | -i, --input <file> | Read content from local file | | --json | Output in JSON format |

Examples:

# Write inline content
codivstack files write sandbox-abc123 /hello.txt "Hello World!"

# Write from local file
codivstack files write sandbox-abc123 /app.js --input ./local-app.js

Delete File/Directory

codivstack files delete <sandboxId> <path> [options]

# Alias
codivstack fs rm <sandboxId> <path>

| Option | Description | |--------|-------------| | --json | Output in JSON format |

Examples:

codivstack files delete sandbox-abc123 /old-file.txt
codivstack fs rm sandbox-abc123 /temp

Create Directory

codivstack files mkdir <sandboxId> <path> [options]

| Option | Description | |--------|-------------| | --json | Output in JSON format |

Examples:

codivstack files mkdir sandbox-abc123 /new-folder
codivstack files mkdir sandbox-abc123 /src/components

Check File Exists

codivstack files exists <sandboxId> <path> [options]

| Option | Description | |--------|-------------| | --json | Output in JSON format |

Examples:

codivstack files exists sandbox-abc123 /package.json

Exit code: 0 if exists, 1 if not exists.

Upload File

codivstack files upload <sandboxId> <localPath> <remotePath> [options]

| Option | Description | |--------|-------------| | --json | Output in JSON format |

Examples:

codivstack files upload sandbox-abc123 ./local-script.sh /scripts/run.sh

Download File

codivstack files download <sandboxId> <remotePath> <localPath> [options]

| Option | Description | |--------|-------------| | --json | Output in JSON format |

Examples:

codivstack files download sandbox-abc123 /output/result.json ./result.json

Command Execution

Execute Command

codivstack exec <sandboxId> <command...> [options]

# Alias
codivstack run <sandboxId> <command...>

| Option | Description | |--------|-------------| | -t, --timeout <seconds> | Command timeout (default: 30) | | -d, --workdir <path> | Working directory | | --json | Output in JSON format |

Examples:

# Run a simple command
codivstack exec sandbox-abc123 ls -la

# Run with timeout
codivstack exec sandbox-abc123 npm install --timeout 120

# Run in specific directory
codivstack exec sandbox-abc123 npm test --workdir /app

# Run complex command
codivstack exec sandbox-abc123 "echo Hello && node app.js"

# Get JSON output
codivstack exec sandbox-abc123 cat package.json --json

JSON Output Mode

All commands support --json flag for machine-readable output:

# List sandboxes as JSON
codivstack sandbox list --json | jq '.[] | .id'

# Get sandbox status as JSON
codivstack sandbox status sandbox-abc123 --json | jq '.status'

# Execute and parse output
codivstack exec sandbox-abc123 cat package.json --json | jq '.stdout | fromjson | .name'

Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | CS_API_KEY | Your CodivStack API key | Yes | | CODIVSTACK_API_KEY | Alternative API key variable | No | | CODIVSTACK_API_URL | Custom API base URL | No |

Exit Codes

| Code | Description | |------|-------------| | 0 | Success | | 1 | Error (API error, validation error, etc.) |

Examples

Complete Workflow

# Set your API key
export CS_API_KEY=your-api-key

# Create a new sandbox
codivstack sandbox create --name my-project --size medium

# Check it's running
codivstack sandbox status sandbox-abc123

# Upload your code
codivstack files upload sandbox-abc123 ./src/index.js /app/index.js
codivstack files upload sandbox-abc123 ./package.json /app/package.json

# Install dependencies
codivstack exec sandbox-abc123 "cd /app && npm install" --timeout 120

# Run your application
codivstack exec sandbox-abc123 "cd /app && node index.js"

# Stop when done
codivstack sandbox stop sandbox-abc123

# Delete if no longer needed
codivstack sandbox delete sandbox-abc123

Scripting Example

#!/bin/bash
export CS_API_KEY=your-api-key

# Create sandbox and capture ID
SANDBOX_ID=$(codivstack sandbox create --size small --json | jq -r '.sandboxId')

echo "Created sandbox: $SANDBOX_ID"

# Run tests
codivstack exec $SANDBOX_ID "npm test" --timeout 300

# Cleanup
codivstack sandbox delete $SANDBOX_ID --force

Troubleshooting

API Key Not Found

Error: API key not found
Please set your API key using: export CS_API_KEY=your-api-key

Make sure you've exported your API key correctly.

Sandbox Not Found

Error: Sandbox not found

Verify the sandbox ID is correct using codivstack sandbox list.

Permission Denied

Error: Permission denied

You can only manage sandboxes you own. Check sandbox ownership.

License

MIT - See LICENSE for details.

Links

• Website: https://codivstack.dev
• Documentation: https://docs.codivstack.dev
• SDK: @codivstack/sdk
• GitHub: https://github.com/codivstack