This guide explains how to install, configure, and use awadm — the administrator CLI to manage Awanio clusters (an alternative interface to the Awanio Dashboard).

Supported OS: macOS/Linux. The commands below assume a POSIX shell (bash/zsh).

Prebuilt binary (example for Linux amd64):

curl -O https://storage.awan.io/assets/awadm-linux-amd64.tar.gz
tar -xvf awadm-linux-amd64.tar.gz
chmod +x ./awadm
sudo mv ./awadm /usr/local/bin/
awadm --version

awadm reads credentials from an awanconfig file. By default it uses:

• Default path: ~/.awan/config
• Override with: —awanconfig /path/to/config

Two ways to configure:

A) Login flow (recommended)

• Exchanges dashboard username/password for API credentials and writes awanconfig.

Example:

awadm config clusters login \
  --name dev3 \
  --username awanio \
  --url https://0.0.0.0/v2
# Prompts for password if --password is omitted

B) Manual setup Create ~/.awan/config with YAML content:

apiVersion: v1
clusters:
  dev-cluster:
    server: https://0.0.0.0/v2
    access-key: sa-xxxxxx
    access-secret: yyyyyy
  demo-cluster:
    server: https://192.168.1.10/v2
    access-key: sa-aaaaaa
    access-secret: bbbbbb
contexts:
  current-context: dev-cluster

Useful config commands:

• Show current context: awadm config context
• Set current context: awadm config context set <cluster-name>
• List clusters: awadm config clusters
• Delete cluster from config: awadm config clusters delete <cluster-name>
• Show config file path and content: awadm config info

Note: The login flow requires the user to be a member of the “root” organization to create service accounts automatically.

Global flags:

• —awanconfig string Path to config file (default: ~/.awan/config)
• -o, —output string Some commands support output format (table or json)

• List VMs:

awadm vm --size-per-page 100 --sort-by id --order desc --page 1 [--search <kw>]

Columns: uuid, Title, Status, Organization, CPU, Ram

• VM detail by UUID:

awadm vm get <vuid> [-o json]

• VM metrics (last 60 minutes, step 10 minutes):

awadm vm metric <vuid> --since-x-minute-ago 60 --minute-step 10

• Export VM metrics to CSV:

awadm vm metric <vuid> --since-x-minute-ago 120 --minute-step 10 --export-path vm_metrics.csv --export-format csv

• JSON output:

awadm vm metric <vuid> --since-x-minute-ago 60 --minute-step 10 -o json

• SNMP-style OID output:

awadm vm metric <vuid> --since-x-minute-ago 60 --minute-step 10 --output snmp --snmp-base-oid .1.3.6.1.4.1.99999.1

• List volumes:

awadm volume

Columns: uuid, Title, Size, Backend Storage

• Volume detail by UUID:

awadm volume get <uuid> [-o json]

• List nodes:

awadm nodes

Columns: name, status, internal_ip, network, mem_ok, disk_ok, pid_ok

Pagination flags:

• -p, —page string Current page in pagination (default: 1)
• -s, —size-per-page string Maximum items number in list output (default: 15)

Example with pagination:

awadm nodes -p 2 -s 20

• Node metrics (CPU and Memory utilization):

awadm nodes metric <node-name> --since-x-minute-ago 60 --minute-step 10

Flags:

• —since-x-minute-ago int Number of minutes ago from now to start the range (mutually exclusive with start/end)
• —start string Start time in layout ‘2006-01-02 15:04:05’
• —end string End time in layout ‘2006-01-02 15:04:05’
• —minute-step int Aggregation minute step
• -o, —output string Output format: table, json or snmp (default: table)
• —snmp-base-oid string Base OID for SNMP output mode (default .1.3.6.1.4.1.99999.2)
• —export-path string Optional file path to export metrics time-series
• —export-format string Export format: csv or spreadsheet (default csv)

Examples:

# Table (default)
awadm nodes metric awid5

# JSON output
awadm nodes metric awid5 -o json

# SNMP-style OID output
awadm nodes metric awid5 -o snmp --snmp-base-oid .1.3.6.1.4.1.99999.2

# Export time-series to CSV
awadm nodes metric awid5 --export-path ./node_metrics_awid5.csv

# Specific time range
awadm nodes metric awid5 --start "2025-08-10 12:00:00" --end "2025-08-10 14:00:00" --minute-step 5

Notes:

• Node metrics API responses have a different JSON structure than VM metrics; the CLI normalizes this internally so outputs and exports are consistent.

• Fibre Channel WWIDs:

awadm nodes storages fibre-channel

Columns: wwid, wwn, size

• List service accounts:

awadm service-accounts

Columns: uuid, AccesKey, Status

• Create a service account:

awadm service-accounts create --name <name> --org-uid <organization-uuid>

Flags:

• —name (required): 6–20 chars; letters, digits, dash (-), underscore (_), dot (.)

• —org-uid (required): organization UUID

• Delete service accounts by UUID(s):

awadm service-accounts delete <uuid> [<uuid> ...]

• List applied licenses:

awadm license

Columns: license key, cluster id, features, maximum cpu socket, expired date

• Add a new license key:

awadm license add <license-key>

• Quick start: login and list VMs

awadm config clusters login --name dev --username admin --url https://0.0.0.0/v2
awadm vm --search web
awadm vm get 00000000-0000-0000-0000-000000000000

• Switch context and list volumes

awadm config context set demo-cluster
awadm volume

• Create a service account via login flow, then create and list SAs

awadm config clusters login --name demo --username admin --url https://192.168.1.10/v2
awadm service-accounts create --name sa-demo --org-uid 00000000-0000-0000-0000-000000000000
awadm service-accounts

• Table output is default for list and detail views.
• JSON output can be requested for some detail commands via -o json.

• Unauthorized or invalid access:

  • Ensure awanconfig has valid access-key and access-secret for the selected context.
  • Verify the server URL is correct and reachable.

• TLS/Certificates:

  • If your environment uses self-signed certs, ensure the server certificate is trusted by your OS. The client may skip TLS verification in some calls, but secure configurations are recommended.

• Login flow fails:

  • Confirm the dashboard credentials are correct.
  • The user must belong to the “root” organization to create service accounts.

• Empty or missing fields in table output:

  • The CLI guards against missing fields (e.g., Status, Organization, Backend Storage), displaying - if unavailable.

• Store and share awanconfig cautiously; it contains API credentials.
• Prefer a least-privilege approach for service accounts.

• Show version:
  • awadm --version
• Show command help:
  • awadm --help or awadm <command> --help