> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arct.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install the Arct CLI and manage servers from your terminal.

`arct` is the command-line client for all 22 public API operations. Preview **`0.1.0rc3`** ships with the Python SDK in `arct-cloud` and requires Python 3.11+. Source and release notes are in [ArctCloud/sdk](https://github.com/ArctCloud/sdk).

## Install

**macOS / Linux**

Install Python 3.11+ with virtual environment support, then run:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/ArctCloud/sdk/main/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
arct --version
```

The installer pins `arct-cloud==0.1.0rc3` in a private environment under `~/.local/share/arct/` and exposes `~/.local/bin/arct`, without sudo. It adds PATH setup to zsh or Bash startup files. Run the printed export in your current terminal; other shells require manual PATH setup. Your system Python packages stay separate.

**Windows / Python environment**

Install into your chosen Python 3.11+ environment:

```powershell theme={null}
python -m pip install "arct-cloud==0.1.0rc3"
python -m arct --version
python -m arct --help
```

The package also installs the `arct` console command. If its scripts directory is on PATH, use `arct`; otherwise replace `arct` below with `python -m arct`. On Windows, `py -3.11` can replace `python` to select the interpreter.

The version command reports `0.1.0rc3`.

### Migrate, Update or Uninstall

Commands, flags, credentials and named contexts remain compatible with the previous Go CLI. Historical [binary releases](https://github.com/ArctCloud/sdk/releases/tag/cli-v0.1.0-rc.2) remain available; new Go CLI binaries are no longer published.

The installer refuses to replace an unrelated executable or symlink at `~/.local/bin/arct`. If your previous Go binary is there, move it aside before installing:

```bash theme={null}
mv "$HOME/.local/bin/arct" "$HOME/.local/bin/arct-go"
```

After installation, check `command -v arct` and `arct --version`. If another old binary takes precedence, put `~/.local/bin` first on PATH or remove that old binary, then open a new terminal.

Rerun the installer to update to its pinned release or repair an installation. Failed package installation preserves the working command; reruns do not duplicate shell profile entries. To uninstall the shell installation:

```bash theme={null}
rm "$HOME/.local/bin/arct"
rm -rf "$HOME/.local/share/arct"
```

Remove the installer-added PATH line from your shell profile if no longer needed. For a package installation, update with `python -m pip install --upgrade "arct-cloud==0.1.0rc3"` or uninstall with `python -m pip uninstall arct-cloud`, using the same environment.

Uninstalling retains saved credentials. Before uninstalling, `arct auth logout --context NAME` or `arct context delete NAME` removes a saved context; neither revokes the dashboard token.

## Authenticate and Start Read-Only

Create a **Read only** token in [Settings > API Tokens](/account/api-tokens.md). Supply it through your environment or secret manager:

```bash macOS / Linux theme={null}
export ARCT_TOKEN="arct_your_token_here"
```

```powershell Windows theme={null}
$env:ARCT_TOKEN = "arct_your_token_here"
```

```bash theme={null}
arct account get
arct servers list
arct servers list --location fra --output json
arct locations list
arct plans list --location fra
arct images list --location fra
```

For saved credentials, `arct auth login --context production` validates an existing token and stores it locally. Input is hidden on an interactive terminal. `arct context use production` selects it; `arct auth status` shows the source without revealing the token. `ARCT_TOKEN` overrides saved contexts. There is no token command-line flag.

`arct auth logout --context production` removes local credentials; it does not revoke the token. Create, disable or delete tokens in the dashboard.

```bash theme={null}
arct context list
arct context use production
arct context delete unused-context
```

`--context NAME` selects a saved context; `ARCT_TOKEN` overrides its token. The credential JSON schema (`active`, named `contexts`, `token`, optional `base_url`) and locations are unchanged. `$XDG_CONFIG_HOME/arct/config.json` takes precedence when set; otherwise the file is `~/.config/arct/config.json` on Linux, `~/Library/Application Support/arct/config.json` on macOS or `%APPDATA%\arct\config.json` on Windows. POSIX credentials use file mode `0600` and directory mode `0700`; Windows protects them with an ACL for the current user and SYSTEM.

The default endpoint is `https://api.arct.cloud/v1`. `--base-url` or `ARCT_BASE_URL` selects another HTTPS endpoint; plain HTTP is allowed only for explicit localhost tests. Redirects are rejected.

## Create and Manage Servers

> [!WARNING]
>
> Use a `read_write` token for mutations. Creation and resize charge the saved card. Paid/destructive operations require confirmation; `--yes` explicitly confirms them for automation. Noninteractive commands without required confirmation fail before mutation.

List locations, plans and images first. Add a public key and select its UUID:

```bash theme={null}
arct ssh-keys create --name my-laptop --public-key-file ~/.ssh/id_ed25519.pub
arct ssh-keys list
arct servers create --hostname web-1 --location fra --plan PLAN_ID \
  --image IMAGE_UUID --ssh-key KEY_UUID --billing-period monthly --yes --wait
```

Replace `PLAN_ID` and `TARGET_PLAN` with plan slugs copied from `arct plans list`. Replace `IMAGE_UUID`, `KEY_UUID` and `SERVER_UUID` with actual resource UUIDs. Image IDs are location-specific; choose an image compatible with the plan. Once running, connect using the returned `login_user` and `ipv4`: `ssh -i ~/.ssh/id_ed25519 USER@IP_ADDRESS`. See [SSH access](/compute/virtual-machines/connect-ssh.md).

```bash theme={null}
arct servers get SERVER_UUID
arct servers stop SERVER_UUID --wait
arct servers start SERVER_UUID --wait
arct servers restart SERVER_UUID --wait
arct servers update SERVER_UUID --delete-protection=true
```

Reinstall wipes the disk. Choose a compatible image and explicitly confirm:

```bash theme={null}
arct servers reinstall SERVER_UUID --image IMAGE_UUID --ssh-key KEY_UUID --yes --wait
```

### Accepted Versus Completed

Without `--wait`, exit `0` can mean **accepted**, rather than finished. Creation returns HTTP `201`; start/stop/restart/reinstall return HTTP `202`. `--wait` polls every 5 seconds, with a default 600-second deadline. Override it with `--timeout 15m` or `--timeout 900`.

```bash theme={null}
arct servers wait SERVER_UUID --status running --timeout 15m
```

Use `--wait` on the original restart/reinstall command to retain transition tracking. A separate `servers wait` checks current status; it cannot prove that an earlier restart completed. A stale initial `running` observation is not accepted as completion by the action waiter. Pre-orders or an unobserved transition can time out as unverified.

Timeouts and interruption stop local waiting; an accepted remote action can continue. Successful create/start/stop/restart/reinstall and status waits show final server fields in table output; JSON preserves the original result with `final_server`. Resize waits add `final_resize_options`; immediate deletion adds `deleted: true`. A wait failure retains the original result with `wait_error` and exits nonzero. One-time passwords stay masked unless you explicitly add `--show-password` to create/reinstall, including after waiting. Tokens remain redacted even with that flag.

### Resize

Stop the server and wait for `stopped`, then inspect the eligible plans and quote:

```bash theme={null}
arct servers stop SERVER_UUID --wait
arct servers resize-options SERVER_UUID
arct servers resize SERVER_UUID --plan TARGET_PLAN --expected-amount 4.12 --yes --wait
```

Replace `4.12` with the exact `amount_due_today` you reviewed. An omitted `--expected-amount` obtains a quote before confirmation and submits that exact amount unchanged; `price_changed` requires a new decision and never silently substitutes a new price.

HTTP `200 applied` and `202 pending_payment` are distinct. Resolve any required payment in the dashboard and confirm the requested plan is applied before running `arct servers start SERVER_UUID --wait`. Resize does not stop or start a server automatically.

### Delete or Schedule Deletion

Immediate deletion wipes the disk and cannot be undone. Delete protection must be off first:

```bash theme={null}
arct servers update SERVER_UUID --delete-protection=false
arct servers delete SERVER_UUID --yes --wait
```

Immediate `--wait` finishes after the acknowledged deletion returns `404` on polling. To keep the server until its paid period ends instead:

```bash theme={null}
arct servers delete SERVER_UUID --at-period-end --yes
arct servers cancel-deletion SERVER_UUID --yes
```

Scheduled deletion reports `cancel_at` and does not support `--wait`. Canceling it restores normal renewal. See [deletion and billing behavior](/api-reference/creating-servers.md#delete-a-server).

## Output, Pagination and Errors

Lists fetch one page by default. `--page` and `--per-page` select a page; `--all` retrieves every page. Single-page JSON preserves `data` and `pagination`; `--all --output json` returns an array.

```bash theme={null}
arct servers list --page 2 --per-page 50 --output json
arct servers list --all --columns id,hostname,status --no-header
arct invoices list --all --output json
```

`--columns` and `--no-header` apply to table output. Results go to stdout; prompts, progress and errors go to stderr. JSON errors are structured and redacted. See [API errors](/api-reference/errors.md), [pagination](/api-reference/pagination.md) and [rate limits](/api-reference/rate-limits.md).

| Exit | Meaning |
| - | - |
| `0` | Success or accepted operation |
| `1` | API or network error |
| `2` | Invalid input or missing confirmation |
| `3` | Timeout, uncertain outcome or unknown charge |
| `130` | Interrupted |

Charge-unknown markers (`order_intent_id` or `payment_pending`) are never automatically retried. Preserve the support identifiers and verify billing before repeating a purchase. A lost response or matching hostname does not prove a successful order.

## Command Controls

Global flags may appear before or after the resource/action. `arct --help` lists resources; `arct RESOURCE ACTION --help` shows command flags.

| Command | Request controls |
| - | - |
| `servers list` | `--status`, `--location` |
| `plans list`, `images list` | `--location` |
| Every API `list` | `--page`, `--per-page`, `--all` |
| `servers create` | `--hostname`, `--location`, `--plan`, `--image`, `--billing-period`, repeated `--ssh-key`, `--coupon-code` or `--coupon-code-null`, `--enable-backups[=false]` |
| `servers update ID` | `--hostname`, `--delete-protection[=false]`, repeated `--label` |
| `servers delete ID` | `--at-period-end[=false]`, `--yes`, immediate `--wait` |
| `servers reinstall ID` | `--image`, `--hostname`, repeated `--ssh-key`, `--yes` |
| `servers resize ID` | `--plan`, `--expected-amount`, `--yes` |
| `ssh-keys create` | `--name`, `--public-key` or `--public-key-file PATH` (`-` reads stdin) |
| `servers wait ID` | `--status`, `--timeout` |

Use `--ssh-key ''` for an explicit empty key array (password access where supported), `--label ''` to clear labels, and `--coupon-code-null` for a null coupon. Omitted fields remain omitted; `--enable-backups=false` and `--delete-protection=false` send explicit false. The CLI does not expose a null resize amount to opt out of price protection.

## Commands and API Boundaries

The API resources are `account`, `servers`, `locations`, `plans`, `images`, `ssh-keys` and `invoices`. Local `auth` and `context` commands manage saved credentials.

`servers create --enable-backups` can enable automatic backups where supported. There are **no backup/snapshot management commands or endpoints**; use the [dashboard](/compute/virtual-machines/backups-snapshots.md). Cards, invoice payment, token issuance/revocation, password resets and VNC are also dashboard operations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.