CLI#

The taskcloud CLI is a thin layer over the REST API. Everything it does, you can do with the API.

Install and log in#

Install script#

Available once the first CLI release is tagged. The script installs a prebuilt binary for Linux or macOS (amd64 or arm64); run curl -fsSL https://task.cloud/install.sh | sh in a terminal.

It detects your OS and architecture, downloads the matching archive from the project's GitHub Releases, verifies its SHA-256 against the release's checksums.txt and installs taskcloud to ~/.local/bin (or /usr/local/bin when run as root). Optional environment variables:

Each release also ships a signed checksum file and SBOMs; the release notes list the cosign and gh attestation verify commands.

Build from source#

Until the first release, and during the private beta, the CLI is built from source (Go 1.27.3+, standard library only); beta participants get access to the source repository:

cd cli && go build -o taskcloud . && sudo mv taskcloud /usr/local/bin/

Log in#

taskcloud login                              # prompts for an API key (opens the dashboard to create one)
taskcloud login --key-stdin < key.txt        # non-interactive (CI)
taskcloud whoami

Coming soon: an npm wrapper (npm install -g @taskcloud/cli) and browser-based login. Until then, taskcloud login asks you to paste a key created in the dashboard.

Credentials are stored in ~/.config/taskcloud/config.json. The TASKCLOUD_API_KEY environment variable takes precedence.

Global flags: --json (machine-readable output; on automatically when stdout is not a TTY), --api-key <key>, --api-url <url>, --quiet.

Cheat sheet#

taskcloud create --template base --size default --name dev   # prints the sandbox ID
taskcloud list                                               # your sandboxes (deleted ones hidden)
taskcloud exec <id> -- npm test                              # exit code = command's exit code
taskcloud shell <id>                                         # PTY session: prints its WebSocket URL
taskcloud ssh <id>                                           # SSH through the gateway
taskcloud cp ./app <id>:/home/user/app -r                    # upload a directory
taskcloud port expose <id> 3000 --public                     # https://<short_id>-3000.taskhost.cloud
taskcloud pause <id>                                         # $0 compute while paused
taskcloud fork <id> --name dev-copy                          # copy with memory
taskcloud fork <id> --count 5 -q                             # 5 copies, all or nothing; prints 5 IDs
taskcloud desktop <id> --ttl 10m --read-only --open          # open the desktop in a browser
taskcloud screenshot <id> -o screen.png
taskcloud input <id> '[{"action":"left_click","coordinate":[640,412]}]' -o after.png
taskcloud delete <id> --yes

Commands#

Sandboxes#

Exec and terminals#

Files#

Networking and desktop#

Snapshots and templates#

Account#

CI example#

taskcloud login --key-stdin <<< "$SANDBOX_API_KEY"
id=$(taskcloud create --template base --size large --batch --ttl 1h --json | jq -r .id)
trap 'taskcloud delete "$id" --yes' EXIT
taskcloud cp . "$id":/home/user/repo -r
taskcloud exec "$id" --cwd /home/user/repo --timeout 600 -- npm ci '&&' npm test

--batch halves the compute price; the sandbox may wait briefly in queued, and exec waits for it to start.