Skip to main content

Arianet CLI

The Arianet CLI (arianet) is the official command-line client for the Arianet cloud platform. It talks to the public Arianet API and lets you order, operate and delete servers, manage SSH keys and firewalls, and read your balance and invoices from a terminal or a script.

Installation​

The CLI is a single static binary. It only talks to the API URL you configure (default https://api.ariaservice.net) and sends no telemetry. Source and release notes: github.com/ariaservice/arianet-cli.

Ubuntu / Debian (apt)

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://ariaservice.github.io/arianet-cli/arianet-archive-keyring.gpg | sudo tee /etc/apt/keyrings/arianet.gpg >/dev/null
echo "deb [signed-by=/etc/apt/keyrings/arianet.gpg] https://ariaservice.github.io/arianet-cli stable main" | sudo tee /etc/apt/sources.list.d/arianet.list
sudo apt update && sudo apt install arianet

macOS / Linux (Homebrew)

brew trust ariaservice/arianet   # recent Homebrew versions require trusting third-party taps
brew install ariaservice/arianet/arianet

The formula (ariaservice/homebrew-arianet) only downloads the release archive from the CLI repository and checks its SHA-256.

Install script (verifies the SHA-256 checksum, and the signature if cosign is installed):

curl -fsSL https://raw.githubusercontent.com/ariaservice/arianet-cli/main/scripts/install.sh | sh

Manual: download the archive and checksums.txt from the releases page, check it with sha256sum --check --ignore-missing checksums.txt, then:

tar -xzf arianet_<version>_<os>_<arch>.tar.gz
sudo install -m 0755 arianet /usr/local/bin/arianet
arianet version

On Windows, download the .zip archive, extract arianet.exe and add its folder to PATH.

To build from source (Go 1.22 or newer):

git clone https://github.com/ariaservice/arianet-cli.git
cd arianet-cli
go build -o arianet ./cmd/arianet
sudo mv arianet /usr/local/bin/

Quick start​

  1. Create an API token at https://cloud.ariaservice.net/users/api-tokens. Give it the scopes you need (see Token scopes).

  2. Save it:

    arianet configure            # paste the token; it is not echoed
    # in scripts: printf '%s' "$ARIANET_TOKEN" | arianet configure --token-stdin

  3. Check that it works:

    arianet auth whoami

  4. Order a server:

    arianet region list                      # pick a region ID
    arianet plan list --region 1             # pick a plan ID
    arianet os list --region 1               # pick an OS ID
    arianet server create --plan 5 --region 1 --os 3 --hostname web-01

Configuration​

The configuration is a config.yaml file in your user config directory (~/.config/arianet/ on Linux, ~/Library/Application Support/arianet/ on macOS). arianet configure show prints its exact location and the active values.

arianet configure                       # interactive setup
arianet configure --token <token>       # set the token
arianet configure --output json         # default output format
arianet configure show                  # show the current configuration

Precedence, highest first: command-line flag, environment variable, config file.

Whenever the API URL is anything other than the default, every command prints a warning on stderr naming the host your token is being sent to and where that setting came from. configure and auth logout rewrite the file from its own contents only, so a token or URL set just for the session (environment variable or flag) is never saved.

Environment variableMeaning
ARIANET_TOKENAPI token
ARIANET_API_URLAPI base URL (default https://api.ariaservice.net)

Global flags​

FlagMeaning
-o, --outputtable (default) or json
--tokenAPI token for this command only
--api-urlAPI base URL for this command only

Every command also accepts --help, which lists its flags with examples.

Token scopes​

A token can be limited to the scopes it needs. A command fails with INSUFFICIENT_SCOPE if the token lacks the matching scope.

CommandsScope
region listregions:read
os listos:read
plan list, plan getplans:read
server list/get/status/actionsservers:read
server create/delete/restart/power-*/reinstall/rename/toggle-protectionservers:write
balance, balance transactionsbalance:read
auth tokens list, auth tokens revoketokens:read, tokens:write (auth whoami and auth logout need none)
balance invoicesinvoices:read
ssh list/get, ssh add/update/deletessh-keys:read, ssh-keys:write
firewall list/get, other firewall commandsfirewalls:read, firewalls:write

A token can also be restricted to a list of source IP addresses; requests from elsewhere fail with IP_NOT_ALLOWED.

Commands​

IDs used by --region, --plan, --os, --ssh-key and --server come from the matching list commands.

Authentication​

arianet auth whoami               # the authenticated user
arianet auth logout               # revoke the current token and forget it
arianet auth tokens list          # list your API tokens
arianet auth tokens revoke <id>   # revoke a token

Catalog​

arianet region list                     # orderable locations
arianet plan list --region <id>         # plans orderable in a region
arianet plan get <id>                   # plan details and pricing
arianet os list --region <id>           # OS templates available in a region

The ID column of region list is the datacenter ID. Pass it as --region everywhere else.

Servers​

List and inspect​

arianet server list
arianet server list --status terminated
arianet server list --page 2 --limit 20
arianet server get <id>
arianet server status <id>
arianet server actions <id> --limit 50

Without --status, list shows active and suspended servers. Other statuses are creating, pending, failed, terminated, powering_on, powering_off, restarting and reinstalling_os.

server actions shows the operations performed on a server (create, restart, reinstall, ...), newest first, with their outcome.

Create​

arianet server create                                   # interactive wizard
arianet server create --plan 5 --region 1 --os 3 --hostname web-01
arianet server create --plan 5 --region 1 --os 3 --ssh-key 2
arianet server create --plan 5 --region 1 --os 3 --password '<root-password>'
arianet server create --plan 5 --region 1 --os 3 --no-wait --yes --output json
FlagMeaning
--planPlan ID
--regionRegion (datacenter) ID
--osOS template ID
--hostnameHostname
--ssh-keyLog in with this stored SSH key instead of a password
--passwordRoot password you choose
--currencyCurrency ID to pay with (default: your default wallet)
--idempotency-keyReuse a key to retry an order safely (see below)
--no-waitReturn as soon as the order is accepted
--timeoutLongest wait for the server to become active (default 15m)
-y, --yesSkip the confirmation prompt
  • With neither --ssh-key nor --password, a strong random root password (letters, digits and a symbol, as the API requires) is generated and printed once. Save it; it cannot be shown again.
  • Without --plan, --region or --os, an interactive wizard asks for them. The wizard needs interactive input, so it is refused with --output json; pass all three IDs in scripts.
  • By default the command waits until the server is active.

Safe retries. Every order carries an idempotency key. If the network fails after you sent the order, running the same command with the same --idempotency-key returns the original result instead of buying a second server. The CLI prints the key when it cannot tell you the outcome. Transient gateway errors are retried automatically with the same key.

Rate limit. Server creation is rate limited per token and per account. When the limit is hit the CLI reports how long to wait before ordering again.

Operate​

arianet server restart <id>   [--wait] [--timeout 15m] [--yes]
arianet server power-on <id>  [--wait]
arianet server power-off <id> [--wait] [--yes]
arianet server reinstall <id> --os <id> [--wait] [--yes]
arianet server delete <id>    [--wait] [--yes]
arianet server rename <id> --name <new-name>      # 1-30 characters
arianet server toggle-protection <id> [--enable | --disable]

Restart, power, reinstall and delete return as soon as the platform has accepted the operation. Add --wait to follow it to the end: progress is written to stderr, and the exit code is non-zero if the operation fails or the timeout passes. These commands are never retried automatically, so a restart is never repeated by accident.

toggle-protection with --enable or --disable sets the state explicitly, which is safe to repeat in scripts. Without either flag the current state is flipped. A protected server can be neither deleted nor reinstalled until protection is turned off.

SSH keys​

arianet ssh list [--page 2 --limit 20]
arianet ssh get <id>
arianet ssh add --name laptop --key-file ~/.ssh/id_ed25519.pub --region <id>
arianet ssh add --name laptop --key "ssh-ed25519 AAAA..." --region <id>
arianet ssh update <id> --name <new-name>
arianet ssh delete <id> [--yes]

An SSH key belongs to one region, so --region is required when adding. Use the key when ordering with --ssh-key <id>.

Firewalls​

arianet firewall list
arianet firewall get <id>
arianet firewall create --name web-fw --region <id> [--description "..."]
arianet firewall update <id> [--name <name>] [--description "..."]
arianet firewall delete <id> [--yes]

arianet firewall rule add <id> --direction ingress --proto tcp --port 443 --remote-ip 0.0.0.0/0
arianet firewall rule add <id> --direction ingress --proto tcp --port 22 --remote-ip 203.0.113.7/32 --description office
arianet firewall rule add <id> --direction ingress --proto icmp --remote-ip 0.0.0.0/0
arianet firewall rule remove <id> <rule-id> [--yes]

arianet firewall attach <id> --server 42,43
arianet firewall detach <id> --server 42
  • A new firewall has no rules. Add rules, then attach it to servers.
  • rule add flags: --direction ingress|egress (default ingress), --proto tcp|udp|icmp|esp|gre (default tcp), --port (a port or range such as 8000-9000, required for tcp and udp), --remote-ip (required), --description.
  • --remote-ip is the allowed source for ingress rules and the allowed destination for egress rules. It is required on purpose: pass 0.0.0.0/0 to allow everyone.
  • The rule ID used by rule remove is a string shown in the Rule ID column of firewall get. It is not a position in the list.
  • attach and detach accept up to 50 servers per call. Repeat --server or separate IDs with commas.

Balance and invoices​

arianet balance                                  # wallet balance
arianet balance transactions [--page 2]
arianet balance invoices [--status paid] [--page 2 --limit 20]
arianet balance invoices get <number>            # one invoice with its line items

Output formats​

The default table output is for people. --output json prints the API data as JSON for scripts:

arianet server list -o json | jq -r '.[] | select(.status == "active") | .id'
arianet server get 42 -o json | jq -r '.ip_addresses[0].ip'

With --output json:

  • stdout carries only the JSON result. Progress, wait output and hints go to stderr.

  • Confirmation prompts are written to stderr. Pass --yes in scripts so they never wait for input (server create does not ask in JSON mode).

  • Errors are written to stderr as

    {"success":false,"error":{"code":"INSUFFICIENT_BALANCE","message":"...","status":402}}

Exit codes​

CodeMeaning
0Success
1Any failure, including a --wait that failed, timed out or could not continue

Scripting examples​

Order a server and capture the result:

out=$(arianet server create --plan 5 --region 1 --os 3 --hostname web-01 \
        --ssh-key 2 --yes --output json) || exit 1
id=$(echo "$out" | jq -r '.id')

Retry safely after a failure, with a key you control:

key="order-$(date +%Y%m%d)-web-01"
until arianet server create --plan 5 --region 1 --os 3 --hostname web-01 \
        --ssh-key 2 --yes --idempotency-key "$key" --output json; do
  sleep 30
done

Restart every active server and wait for each:

for id in $(arianet server list -o json | jq -r '.[] | select(.status == "active") | .id'); do
  arianet server restart "$id" --yes --wait
done

Troubleshooting​

Message / codeCause and fix
No API token configuredRun arianet configure --token <token> or set ARIANET_TOKEN.
UNAUTHORIZEDThe token is wrong, revoked or expired. Check arianet configure show and create a new token.
INSUFFICIENT_SCOPEThe token lacks the scope for this command. Create a token with the scope (see above).
IP_NOT_ALLOWEDThe token is restricted to other source IP addresses. Run the command from an allowed address or use a token without the restriction.
INSUFFICIENT_BALANCETop up the wallet, then retry. arianet balance shows the current balance.
NO_DEFAULT_WALLETYou have no default wallet. Pass --currency <id>.
FEATURE_NOT_SUPPORTEDThe region does not offer SSH keys or firewalls. arianet region list shows yes/no per region in the SSH KEYS and FIREWALLS columns.
RATE_LIMIT_EXCEEDEDToo many requests. The message says how long to wait.
UPSTREAM_ERROR / UPSTREAM_UNAVAILABLE / WRITES_UNAVAILABLEThe platform is temporarily unavailable. Wait and retry. A server order can be retried with the same --idempotency-key.
VALIDATION_ERRORAn argument was rejected. The message names the field.

If server create is interrupted after the order was sent, check arianet server list before ordering again, or re-run the same command with the printed --idempotency-key.

Support​