TheStage AI: CLI Reference

Attention

TheStage CLI requires an API token from the TheStage AI Platform. Generate one at Profile > API tokens in the web interface.

TheStage CLI lets you manage GPU infrastructure and run code on remote machines — all from your laptop. No need to remember IP addresses or juggle SSH configs: connect to any instance or container by name, launch tasks on powerful GPU servers with a single command, and stream output back to your terminal in real time.

With the CLI you can:

• Manage instances — rent GPU servers, list, connect, restart, and terminate them

• Manage containers — create, start, stop, connect, transfer files, and stream logs

• Run tasks in projects — organize code, execute it remotely on containers, and monitor logs in real time

• Configure access — set API tokens, upload SSH keys

Installation

pip install thestage

# Upgrade to the latest version
pip install thestage --upgrade

# Verify installation
thestage version

Requirements: Python 3.9+, Git, SSH client. Linux or macOS recommended; on Windows use WSL.

Configuration

Command	Description
thestage config set	Set access token
thestage config get	Display configuration
thestage config clear	Clear configuration
thestage config upload-ssh-key	Upload SSH key to platform

Set your API token to authenticate with TheStage AI backend. Tokens are generated in the web interface at Profile > API tokens.

# Set access token
thestage config set --access-token <TOKEN>

# View current configuration
thestage config get

# Clear all configuration
thestage config clear

Upload SSH key

Upload your public SSH key to the platform and optionally to a specific rented instance.

# Upload SSH key to the platform
thestage config upload-ssh-key ~/.ssh/id_rsa.pub

# Upload SSH key to the platform and a specific rented instance
thestage config upload-ssh-key ~/.ssh/id_rsa.pub --instance-rented-id <INSTANCE_ID>

Options

• ssh_public_key (required) - Path to your public SSH key file or the key contents. OpenSSH format required.

• --instance-rented-id, -rid - Rented instance ID to add the key to

• --instance-rented-name, -rn - Rented instance name to add the key to

Quick connect

thestage connect is a universal shortcut to SSH into any instance, container, or task by its name or ID.

thestage connect <NAME_OR_ID>

# Self-hosted instances require a username
thestage connect <NAME_OR_ID> --username <USER>

# Optionally specify a private key
thestage connect <NAME_OR_ID> --private-key-path ~/.ssh/id_rsa

Instance Management

Command	Description
thestage instance rented ls	List rented instances
thestage instance rented create	Rent a new instance
thestage instance rented connect	SSH into rented instance
thestage instance rented restart	Restart rented instance
thestage instance rented terminate	Terminate rented instance
thestage instance self-hosted ls	List self-hosted instances
thestage instance self-hosted connect	SSH into self-hosted instance

Instances are GPU servers — either rented from cloud providers or self-hosted machines connected to your account.

Rented instances

List instances

# List all rented instances
thestage instance rented ls --status all

# Filter by status (e.g. online, offline)
thestage instance rented ls --status online

Options

• --status, -s - Filter by status. Use all to list everything.

• --row, -r - Rows per page (default: 5)

• --page, -p - Starting page (default: 1)

Create instance

thestage instance rented create \
    --name my-gpu-server \
    --provider Nebius \
    --gpu H100 \
    --num-gpu 1 \
    --disk-size 200

# Skip confirmation prompt
thestage instance rented create -n my-server -p Amazon -g A100 -ng 1 -ds 100 --force-yes

Options

• --name, -n - Instance name

• --provider, -p - Cloud provider (Amazon, Nebius)

• --gpu, -g - GPU type (A100, A10G, H100, L40S, T4)

• --num-gpu, -ng - Number of GPUs

• --disk-size, -ds - Disk size in GB

• --force-yes, -f - Skip confirmation prompt

Connect to instance

thestage instance rented connect --rented-instance-id <ID>
thestage instance rented connect --rented-instance-name <NAME>

# Or use the universal shortcut
thestage connect <NAME_OR_ID>

Restart / terminate instance

thestage instance rented restart --rented-instance-id <ID>
thestage instance rented terminate --rented-instance-name <NAME>

Self-hosted instances

List instances

thestage instance self-hosted ls --status all
thestage instance self-hosted ls --status online

Options

• --status, -s - Filter by status. Use all to list everything.

• --row, -r - Rows per page (default: 5)

• --page, -p - Starting page (default: 1)

Connect to instance

Self-hosted instances require a --username because the platform does not store SSH user info.

thestage instance self-hosted connect --self-hosted-instance-id <ID> --username <USER>

# Or use the universal shortcut
thestage connect <NAME_OR_ID> --username <USER>

Container Management

Command	Description
thestage container ls	List containers
thestage container info	Show container details
thestage container create	Create a new container
thestage container start	Start container
thestage container stop	Stop container
thestage container restart	Restart container
thestage container delete	Delete container
thestage container connect	SSH into container
thestage container upload	Upload file to container
thestage container download	Download file from container
thestage container logs	Stream or view container logs
thestage container image ls	List available Docker images

Containers are Docker environments running on your instances. You can create, start, stop, connect, transfer files, and stream logs — all from the CLI.

List containers

# List all containers
thestage container ls --status all

# Filter by status
thestage container ls --status running

# Filter by project
thestage container ls --project-name my-project

Options

• --status, -s - Filter by status. Use all to list everything.

• --project-id, -pid - Filter by project ID

• --project-name, -pn - Filter by project name

• --row, -r - Rows per page (default: 5)

• --page, -p - Starting page (default: 1)

Get container info

thestage container info --container-id <ID>
thestage container info --container-name <NAME>

Create container

thestage container create \
    --container-name my-container \
    --rented-instance-name my-gpu-server \
    --project-name my-project \
    --image pytorch/pytorch:latest \
    --gpu-number 1 \
    --volume /data:/workspace/data

Options

• --container-name, -cn - Container name

• --rented-instance-id, -rid / --rented-instance-name, -rn - Rented instance to run on

• --self-hosted-instance-id, -sid / --self-hosted-instance-name, -sn - Self-hosted instance to run on

• --project-id, -pid / --project-name, -pn - Project to associate with (defaults to current directory)

• --working-directory, -wd - Path to working directory

• --image, -i - Docker image name (interactive selection if omitted)

• --gpu-number, -gpun - Number of GPUs (no limit by default)

• --cpu-number, -cpun - Number of CPUs (no limit by default)

• --volume, -v - Volume mount in /host:/container format (repeatable)

List available images

thestage container image ls

Lifecycle: start, stop, restart, delete

thestage container start --container-name <NAME>
thestage container stop  --container-name <NAME>
thestage container restart --container-id <ID>
thestage container delete --container-name <NAME>

All lifecycle commands accept --container-id, -cid or --container-name, -cn.

Connect to container

The CLI connects via SSH to the host instance first, then into the container.

# Container on a rented instance
thestage container connect --container-name <NAME>

# Container on a self-hosted instance (username required)
thestage container connect --container-name <NAME> --username <USER>

# Or use the universal shortcut
thestage connect <NAME_OR_ID>

Upload and download files

File transfers go through the host instance via SSH.

# Upload a local file to a container
thestage container upload ./model.pt my-container:/workspace/models/

# Download a file from a container
thestage container download my-container:/workspace/results/output.csv ./results/

# For self-hosted instances, add --username
thestage container upload ./data.tar my-container:/data/ --username <USER>

Format: <container_name_or_id>:/path/inside/container

Stream container logs

# Stream real-time logs
thestage container logs --container-name <NAME>

# View last N log entries (no streaming)
thestage container logs --container-name <NAME> --number 100

Project & Task Management

Command	Description
thestage project ls	List projects
thestage project init	Initialize project from local directory
thestage project clone	Clone project repository
thestage project checkout	Checkout branch or task
thestage project pull	Pull latest changes
thestage project reset	Hard reset to remote
thestage project delete	Delete project
thestage project attach-instance	Attach instance to project
thestage project detach-instance	Detach instance from project
thestage project run	Run a task on remote container
thestage project config get	View project config
thestage project config set-default-container	Set default container for tasks
thestage project task ls	List project tasks
thestage project task logs	Stream or view task logs
thestage project task cancel	Cancel a running task

Projects organize your code and tasks across instances. Each project gets a dedicated Git repository managed by TheStage. You write code locally, then run it remotely on any container attached to the project.

List projects

thestage project ls

# Filter by instance
thestage project ls --rented-instance-name my-gpu-server

Options

• --rented-instance-id, -rid / --rented-instance-name, -rn - Filter by rented instance

• --self-hosted-instance-id, -sid / --self-hosted-instance-name, -sn - Filter by self-hosted instance

• --status, -s - Filter by status

• --row, -r - Rows per page (default: 5)

• --page, -p - Starting page (default: 1)

Initialize or clone a project

Use init to start tracking an existing local directory in a project, or clone to download a project repository to a local directory.

# Initialize existing code into a project
thestage project init --project-name my-project --working-directory ./my-code

# Initialize from a public Git repository
thestage project init --project-name my-project --remote https://github.com/user/repo.git

# Clone a project repository
thestage project clone --project-name my-project --working-directory ./workspace

Options

• --project-id, -pid / --project-name, -pn - Project identifier (required)

• --working-directory, -wd - Path to working directory (defaults to current directory)

• --remote, -r - Public Git repository URL to initialize from (init only)

Repository operations

Standard Git-like operations for the project repository.

# Checkout a specific task or branch
thestage project checkout --task-id <TASK_ID>
thestage project checkout --branch feature/experiment

# Checkout main branch
thestage project checkout --branch /

# Pull latest changes
thestage project pull

# Hard reset to remote (discards local changes)
thestage project reset

All commands accept --working-directory, -wd to specify the project directory.

Attach / detach instances

Attach or detach compute instances from a project.

# Attach a rented instance to a project
thestage project attach-instance --project-name my-project --rented-instance-name my-server

# Detach a self-hosted instance
thestage project detach-instance --project-name my-project --self-hosted-instance-id <ID>

Delete project

thestage project delete --project-name my-project

Project config

# View local project config
thestage project config get

# Set a default container for task execution
thestage project config set-default-container --container-name my-container

# Unset the default container
thestage project config set-default-container --unset

Run tasks

Submit code to run on a remote container. By default, local changes are auto-committed and real-time logs are streamed.

# Run a command in the default container
thestage project run python train.py

# Specify a container explicitly
thestage project run --container-name my-container python train.py --epochs 100

# Run with a specific commit
thestage project run --commit-hash abc123 python evaluate.py

# Add specific files to the auto-commit
thestage project run --files-add config.yaml,data/params.json python train.py

# Skip auto-commit (use existing HEAD)
thestage project run --skip-autocommit python inference.py

# Run without log streaming
thestage project run --no-logs python long_job.py

Options

• command (required) - Command to execute

• --container-id, -cid / --container-name, -cn - Target container

• --working-directory, -wd - Project directory

• --commit-hash, -hash - Specific commit to use (defaults to current HEAD)

• --title, -t - Custom task title (defaults to git commit message)

• --files-add, -fa - Comma-separated list of files to add to the auto-commit

• --skip-autocommit, -sa - Skip automatic commit of changes

• --no-logs, -nl - Disable real-time log streaming

Note

Log controls: While streaming logs, press Ctrl+C to cancel the task, or Ctrl+D to detach from the log stream without stopping the task. Multiple tasks on the same container are queued and executed sequentially.

Manage tasks

# List tasks for a project
thestage project task ls --project-name my-project

# Stream real-time task logs
thestage project task logs <TASK_ID>

# View last N log entries
thestage project task logs <TASK_ID> --number 50

# Cancel a running task
thestage project task cancel <TASK_ID>

• TheStage AI: CLI Reference
  • Installation
  • Configuration
    • Upload SSH key
    • Quick connect
  • Instance Management
    • Rented instances
      • List instances
      • Create instance
      • Connect to instance
      • Restart / terminate instance
    • Self-hosted instances
      • List instances
      • Connect to instance
  • Container Management
    • List containers
    • Get container info
    • Create container
      • List available images
    • Lifecycle: start, stop, restart, delete
    • Connect to container
    • Upload and download files
    • Stream container logs
  • Project & Task Management
    • List projects
    • Initialize or clone a project
    • Repository operations
    • Attach / detach instances
    • Delete project
    • Project config
    • Run tasks
    • Manage tasks