Skip to content

CLI

Every command of the Sutra CLI.

The CLI uses the same nouns and verbs as the API. Commands that create or delete print the resource name, and every command prints JSON instead of text when you ask for it.

Today’s CLI is anchor. Log in once with anchor auth login (see the Quickstart), or pass --api-url and --token to each command. It also reads the key from ANCHOR_API_TOKEN.

Global flags: --json for JSON output, --profile to pick a saved profile, --config for another config file.

--project and the profile take a project id or a longer form of the project’s name. A command takes a sandbox by its id, and a process or a port as <sandbox>/<id>. A full name works too. A command or flag the CLI does not have, and an argument a command does not take, is an error: the CLI sends nothing and exits with 1.

The Sutra CLI is sutra. Log in once with sutra auth login; it saves the API key and project in a profile.

Global flags: --output json for JSON output, --profile to pick a saved profile.

Durations take a unit, such as 30s, 15m or 1h. Sizes take one too, such as 5GiB.

Log in and profiles

Command What it does
anchor auth login Save an API key, API URL and project in a profile.
anchor auth logout Remove the saved key from a profile.
anchor auth status Show the active profile.
anchor config list List profiles.
anchor config show Show a profile.
anchor config use <profile> Switch to another profile.
Command What it does
sutra auth login Save an API key and project in a profile.
sutra auth logout Remove the saved key.
sutra auth status Show the active profile.

Sandboxes

Command What it does
anchor sandbox create Create a sandbox. --name chooses its id; without it Sutra assigns one. The CLI cannot attach an integration yet.
anchor sandbox get <sandbox> Show a sandbox.
anchor sandbox list List running sandboxes. --state all lists the others too.
anchor sandbox stop <sandbox> Stop a sandbox. Prints the operation id and returns before the sandbox has stopped.
anchor sandbox delete <sandbox> Delete a sandbox. A running sandbox is stopped first.
Command What it does
sutra sandboxes create <sandbox> Create a sandbox. Flags include --template, --snapshot, --volume, --integration, --egress, --timeout and --idle-timeout.
sutra sandboxes get <sandbox> Show a sandbox.
sutra sandboxes list List sandboxes.
sutra sandboxes update <sandbox> Change labels, the lifecycle policy, environment, integrations or --egress.
sutra sandboxes stop <sandbox> Stop a sandbox.
sutra sandboxes start <sandbox> Start a stopped sandbox.
sutra sandboxes delete <sandbox> Delete a sandbox.

Processes

Command What it does
anchor sandbox exec <sandbox> -- <command> Run a command and wait for it. Prints its output, and exits with 1 when the command exits with another code than 0. With --json it prints the result, with the code in exitCode, and exits with 0.
anchor sandbox process start <sandbox> -- <command> Start a long-running process. --process-id names it. Exits with 1 when the command cannot be started.
anchor sandbox process get <sandbox>/<process> Show a process.
anchor sandbox process wait <sandbox>/<process> Wait for a process to end. --timeout is at most 5m.
anchor sandbox process logs <sandbox>/<process> Read a process’s output.
anchor sandbox process kill <sandbox>/<process> End a process with SIGKILL.
Command What it does
sutra processes run <sandbox> -- <command> Run a process and wait for it. --wait limits the wait. Exits with the process’s exit code.
sutra processes start <sandbox> -- <command> Start a process and return. --id names it.
sutra processes get <sandbox> <process> Show a process.
sutra processes list <sandbox> List processes.
sutra processes wait <sandbox> <process> Wait for a process to end.
sutra processes output <sandbox> <process> Print a process’s output.
sutra processes signal <sandbox> <process> <signal> Send a signal. --escalate-after sends SIGKILL later if it still runs.

Files

Command What it does
anchor sandbox fs upload <sandbox> <local> <remote> Upload a file.
anchor sandbox fs download <sandbox> <remote> <local> Download a file.
anchor sandbox fs upload-archive <sandbox> <local> <remote> Upload a tar archive or a local folder.
anchor sandbox fs download-archive <sandbox> <remote> <local> Download paths as a tar archive.
anchor sandbox fs list <sandbox> <path> List a folder.
anchor sandbox fs info <sandbox> <path> Show a path’s size, type and mode.
anchor sandbox fs mkdir <sandbox> <path> Create a folder.
anchor sandbox fs mv <sandbox> <source> <target> Move or rename.
anchor sandbox fs cp <sandbox> <source> <target> Copy.
anchor sandbox fs chmod <sandbox> <path> <mode> Change a path’s mode.
anchor sandbox fs delete <sandbox> <path> Delete a file or folder.
anchor sandbox fs find <sandbox> <path> <pattern> Find files by name.
anchor sandbox fs search <sandbox> <path> <pattern> Search file contents.
anchor sandbox fs replace <sandbox> <path> <pattern> <replacement> Replace text in files.
Command What it does
sutra files write <sandbox> <path> Write standard input to a file.
sutra files read <sandbox> <path> Print a file.
sutra files list <sandbox> <path> List a folder.
sutra files info <sandbox> <path> Show a path’s size, type and mode.
sutra files mkdir <sandbox> <path> Create a folder.
sutra files move <sandbox> <source> <destination> Move or rename.
sutra files copy <sandbox> <source> <destination> Copy.
sutra files delete <sandbox> <path> Delete a file, or a folder with --recursive.
sutra files upload-archive <sandbox> <path> Unpack a tar archive from standard input into a folder.
sutra files download-archive <sandbox> <path>... Write a tar archive of the paths to standard output.

Ports

Command What it does
anchor sandbox preview open <sandbox> --port <port> --key <key> Open a port and print its host. Private unless you pass --access-mode public. --all-ports serves every port of the sandbox through it.
anchor sandbox preview list <sandbox> List a sandbox’s ports.
anchor sandbox preview close <sandbox>/<key> Close a port.
Command What it does
sutra ports create <sandbox> <port> Create a port. Private unless you pass --access public.
sutra ports get <sandbox> <port> Show a port and its address.
sutra ports list <sandbox> List ports.
sutra ports update <sandbox> <port> Change a port’s --access.
sutra ports sign <sandbox> <port> Print a signed link. --expires-in sets how long it works.
sutra ports delete <sandbox> <port> Delete a port.

SSH access

Command What it does
anchor sandbox ssh <sandbox> Register your local SSH key and connect.
anchor sandbox ssh credential <sandbox> Get a password for SSH access.
anchor sandbox ssh keys add|remove|set <sandbox> Manage the SSH keys a sandbox accepts.
anchor sandbox access open|update|close Manage SSH access to a sandbox directly.
anchor sandbox access credential <credential> Get a credential for SSH access.
Command What it does
sutra ssh <sandbox> Issue a credential and connect with ssh.

Templates, snapshots and volumes

Not available yet.

Command What it does
sutra templates create <template> Create a template.
sutra templates versions create <template> Create a version from --image or --snapshot, with defaults such as --port and --process.
sutra templates get|list|delete Show, list or delete templates.
sutra templates versions get|list Show or list versions.
sutra snapshots create <snapshot> --sandbox <sandbox> Create a snapshot. --includes sets what it holds.
sutra snapshots get|list|delete Show, list or delete snapshots.
sutra volumes create <volume> --size <size> Create a volume.
sutra volumes get|list|delete Show, list or delete volumes.

Agents

Apps are the earlier form of agents.

Command What it does
anchor app deploy --file <manifest> Deploy an app from a manifest.
anchor app render --file <manifest> Print the manifest with all values filled in.
anchor app list List apps.
anchor app instances <app> List an app’s sandboxes.
anchor app stop <app> Stop an app.
anchor app start <app> Start a stopped app.
anchor app delete <app> Delete an app.
Command What it does
sutra agents create <agent> -- <command> Create an agent from --image, with --protocol, --idle-timeout and --session-volume.
sutra agents get|list|delete Show, list or delete agents.
sutra agents update <agent> Make another revision active.
sutra agents invoke <agent> Send --input to a session. --session picks the session.
sutra agents revisions create|get|list <agent> Create, show or list revisions.
sutra agents sessions list <agent> List sessions.
sutra agents sessions get <agent> <session> Show a session.
sutra agents sessions stop <agent> <session> Stop a session.

Services

Not available yet.

Command What it does
sutra services create <service> -- <command> Create a service from --image that serves --port.
sutra services get|list|delete Show, list or delete services.
sutra services update <service> Make another revision active.
sutra services revisions create|get|list <service> Create, show or list revisions.

Operations

Not available yet.

Command What it does
sutra operations get|list Show or list operations.
sutra operations wait <operation> Wait for an operation to finish.

Type to search…

↑↓ navigate↵ selectEsc close