CLI

Use Archipelag.io from the command line with the official CLI tool

CLI

The official command-line interface for Archipelag.io. A single binary that talks to both the HTTP API and the NATS message fabric. Built in Rust.

The binary is called island.

Installation

{% tab(name="macOS (Apple Silicon)") %} ```bash curl -L https://github.com/archipelag-io/island-cli/releases/latest/download/island-darwin-arm64.tar.gz | tar xz sudo mv island /usr/local/bin/ ```

```bash curl -L https://github.com/archipelag-io/island-cli/releases/latest/download/island-darwin-amd64.tar.gz | tar xz sudo mv island /usr/local/bin/ ```

```bash curl -L https://github.com/archipelag-io/island-cli/releases/latest/download/island-linux-amd64.tar.gz | tar xz sudo mv island /usr/local/bin/ ``` A statically-linked musl build is also available as `island-linux-amd64-musl`.

```bash curl -L https://github.com/archipelag-io/island-cli/releases/latest/download/island-linux-arm64.tar.gz | tar xz sudo mv island /usr/local/bin/ ```

Download `island-windows-amd64.zip` from the [latest release](https://github.com/archipelag-io/island-cli/releases/latest). The zip contains `island.exe`. Add the directory to your PATH.

```bash cargo install --git https://github.com/archipelag-io/island-cli ``` This installs the `island` binary.

```bash docker run --rm ghcr.io/archipelag-io/island-cli --help ``` Or with your API key: ```bash docker run --rm -e ARCHIPELAG_API_KEY=ak_xxx ghcr.io/archipelag-io/island-cli account ``` The `island` binary is available inside the container.

{% end %}

Verify it works:

island --version

Authentication

### Log in with your API key ```bash island auth login ``` You'll be prompted to enter your API key. Get one from [Settings → API Keys](https://app.archipelag.io/settings/api-keys). You can also pass it directly: ```bash island auth login --key ak_your_key_here ``` ### Verify your connection ```bash island auth status ``` This shows your account email and credit balance.

Configuration

Your API key is saved to ~/.island/config.toml:

api_key = "ak_your_key_here"

You can also configure via environment variables or CLI flags. The precedence order is:

CLI flag (--api-key)
Environment variable (ARCHIPELAG_API_KEY)
Config file (~/.island/config.toml)

Variable	Default	Description
`ARCHIPELAG_API_KEY`	—	API key
`ARCHIPELAG_API_URL`	`https://api.archipelag.io`	API base URL
`ARCHIPELAG_NATS_URL`	`nats://sail.archipelag.io:4222`	NATS server URL

Chat

The chat command sends a prompt and streams the response token by token:

island chat "Explain quantum computing in one paragraph"

Options

# Add a system prompt
island chat "Write a haiku" --system "You are a poet"

# Control generation parameters
island chat "Hello" --max-tokens 100 --temperature 0.5

# Wait for the full response instead of streaming
island chat "Hello" --no-stream

# Use a specific Cargo
island chat "Hello" --workload llm-chat

Flag	Short	Description
`--system`	`-s`	System prompt
`--max-tokens`	`-m`	Maximum tokens to generate
`--temperature`	`-t`	Sampling temperature (0.0–2.0)
`--workload`	`-w`	Cargo slug (default: `llm-chat`)
`--no-stream`	—	Disable streaming

Jobs

Jobs are the core unit of work on Archipelag.io. Every chat message, image generation, or custom Cargo runs as a job.

Submit a job

island jobs submit --workload llm-chat --input '{"prompt": "Hello!"}' --stream

The --stream flag prints output tokens as they arrive. Without it, the command returns the job ID immediately.

List jobs

island jobs list

ID                                     STATUS       WORKLOAD         DURATION   CREATED
a1b2c3d4-...                           completed    llm-chat         1.2s       2026-03-14T09:00:00Z
e5f6g7h8-...                           running      sdxl             -          2026-03-14T09:01:00Z

Pagination:

island jobs list --limit 50 --offset 20

Get job details

island jobs get a1b2c3d4-e5f6-7890-abcd-1234567890ab

Stream job output

Attach to a running job and stream its output:

island jobs stream a1b2c3d4-e5f6-7890-abcd-1234567890ab

Cancel a job

island jobs cancel a1b2c3d4-e5f6-7890-abcd-1234567890ab

Account

Check your credit balance and account info:

island account

Account
  Email:   you@example.com
  ID:      42
  Credits: 9850.00

Cargos

Browse the available compute Cargos on the network.

List Cargos

island workloads list

SLUG                 NAME                           RUNTIME      PRICE      ENABLED
llm-chat             LLM Chat (Mistral 7B)          container    0.0100     yes
sdxl                 Stable Diffusion XL             container    0.0500     yes
llm-chat-mobile      LLM Chat (Mobile)              llmcpp       0.0050     yes

Get Cargo details

island workloads get llm-chat

Islands (Hosts)

View the compute Islands currently on the network:

island hosts list

ID                                     NAME             STATUS     REGION     KARMA
f9e8d7c6-...                           gpu-beast-01     online     eu-west    98.5
b5a4c3d2-...                           ml-node-03       online     us-east    95.2

Get details for a specific Island:

island hosts get f9e8d7c6-b5a4-3210-fedc-ba9876543210

API Keys

Manage your API keys without leaving the terminal.

List keys

island api-keys list

Create a key

island api-keys create "ci-pipeline"

Save your key

The full API key is only shown once at creation time. Copy it immediately.

Delete a key

island api-keys delete <key-id>

Market Rates

View current pricing on the Archipelag.io Compute Exchange:

island market rates

CARGO                AVG          MIN          MAX          HOSTS
llm-chat             0.0100       0.0080       0.0120       12
sdxl                 0.0500       0.0400       0.0600       5

Filter by Cargo:

island market rates llm-chat

View price history:

island market history llm-chat

Sail (NATS)

Subscribe directly to the Archipelag.io message fabric at sail.archipelag.io. This is a power-user feature for debugging, monitoring, or building custom tooling.

# Watch all Island heartbeats
island sail subscribe "host.*.heartbeat"

# Watch job status updates for a specific Island
island sail subscribe "host.f9e8d7c6.status"

# Limit to 10 messages
island sail subscribe "host.*.heartbeat" --max 10

Messages are pretty-printed as JSON. Each line shows the message sequence number, subject, and payload.

NATS subjects

Common subjects: | Subject | Description | |---------|-------------| | `host.{id}.heartbeat` | Island heartbeat with load metrics | | `host.{id}.status` | Job status updates | | `host.{id}.output` | Job output chunks (streaming) | | `host.{id}.jobs` | Job assignments from the coordinator | | `coordinator.hosts.register` | Island registration events |

Output Formats

Every command supports --format json for machine-readable output, making it easy to integrate with scripts and other tools:

# Pipe to jq
island account --format json | jq '.credits'

# Use in shell scripts
CREDITS=$(island account --format json | jq -r '.credits')
if (( $(echo "$CREDITS < 10" | bc -l) )); then
  echo "Low credits!"
fi

# Export job list as JSON
island jobs list --format json > jobs.json

Shell Completions

Generate completions for your shell:

{% tab(name="Bash") %} ```bash island completion bash >> ~/.bashrc source ~/.bashrc ```

```bash island completion zsh >> ~/.zshrc source ~/.zshrc ```

```bash island completion fish > ~/.config/fish/completions/island.fish ```

{% end %}

Global Options

These flags work with any command:

Flag	Environment Variable	Default	Description
`--api-url`	`ARCHIPELAG_API_URL`	`https://api.archipelag.io`	API base URL
`--api-key`	`ARCHIPELAG_API_KEY`	—	API key
`--nats-url`	`ARCHIPELAG_NATS_URL`	`nats://sail.archipelag.io:4222`	NATS server URL
`--format`	—	`text`	Output format (`text` or `json`)
`--help`	—	—	Show help
`--version`	—	—	Show version

Command Reference

Command	Description
`island auth login`	Save API key
`island auth status`	Show authentication status
`island auth logout`	Remove saved credentials
`island account`	Show account info and credits
`island chat <prompt>`	Chat with an AI model (streaming)
`island jobs list`	List your compute jobs
`island jobs submit`	Submit a new job
`island jobs get <id>`	Get job details
`island jobs stream <id>`	Stream job output
`island jobs cancel <id>`	Cancel a running job
`island workloads list`	List available Cargos
`island workloads get <slug>`	Get Cargo details
`island hosts list`	List online Islands
`island hosts get <id>`	Get Island details
`island api-keys list`	List API keys
`island api-keys create <name>`	Create a new API key
`island api-keys delete <id>`	Delete an API key
`island market rates [slug]`	Show current market rates
`island market history <slug>`	Price history for a Cargo
`island sail subscribe <subject>`	Subscribe to NATS messages
`island completion <shell>`	Generate shell completions

CLI

CLI

Installation

Authentication

Configuration

Chat

Options

Jobs

Submit a job

List jobs

Get job details

Stream job output

Cancel a job

Account

Cargos

List Cargos

Get Cargo details

Islands (Hosts)

API Keys

List keys

Create a key

Delete a key

Market Rates

Sail (NATS)

Output Formats

Shell Completions

Global Options

Command Reference

Resources