Quickstart

1. Install the CLI

curl -fsSL https://downloads.amics.ai/cli/install.sh | sh
amics --version

The installer selects a standalone executable for macOS or Linux, verifies its checksum, and installs it to ~/.local/bin. macOS executables are signed and notarized. The CLI does not require Bun, Node.js, Python, or a package manager at runtime.

On a first interactive install, accept the prompt to complete sign-in and skill installation now. If you accept, skip steps 2 and 3 below.

2. Sign in

amics login

The CLI opens a short-lived browser approval flow and stores the workspace credential with private file permissions. For a headless machine:

amics login --no-browser

Open the printed URL on another device. In CI, set AMICS_API_KEY instead.

3. Install the agent skill

amics skill install

The CLI detects local coding agents and asks where to install the skill. Use --agent codex or another supported agent name to choose targets explicitly, --agent universal for ~/.agents/skills, or --copy when symlinks are unavailable.

The installed package follows the portable Agent Skills layout used by skills.sh, so supported agents can discover the same SKILL.md. The public catalog also includes Agent Plugins 1.0 and Codex manifests for plugin-aware clients; both load this skill and still use the local CLI for execution.

4. Start with your agent

Ask your coding agent:

Use $amics to compare live GPU options for this workload. Ask before acquiring compute.

Or run the CLI directly:

amics gpu options --min-vram 24 --max-runtime 30m

# Replace this placeholder with a family returned above, without spaces.
amics run \
  --gpu CHOSEN_GPU_IDENTIFIER --min-vram 24 \
  --max-hourly-price 1.50 --max-runtime 30m \
  -- nvidia-smi --query-gpu=name,memory.total --format=csv,noheader

The options command prints current family labels and prices. Choose a family that fits the workload, then remove spaces from its label for --gpu (RTX 4090 becomes RTX4090). Replace the example price and runtime with bounds you are prepared to approve.

By default, discovery and execution include all verified hosts, including community-operated machines. Use --host datacenter on both commands for sensitive source or forwarded environment values.

--max-hourly-price is the maximum total compute rate in USD per hour. --max-runtime bounds the command. Arguments after -- are passed literally. The interactive run shows its acquisition plan and asks for confirmation. A successful smoke run prints the detected GPU name and memory, then stops the auto-acquired compute.

For an unattended run, add --yes only after a person or explicit policy has approved the complete acquisition envelope. The caller must provide all three of --yes, --max-hourly-price, and --max-runtime.

5. Know what happens next

Amics snapshots the selected project, acquires compatible Spot capacity, runs the command, streams stdout and stderr, and stops auto-acquired compute after the command. Spot capacity can be interrupted. Amics keeps the run and its logs for inspection but never blindly submits a second copy.

Troubleshoot setup

Start with:

amics doctor

It validates the CLI, credential, control plane, agent skill, and PATH, and prints the exact fix for each failed check. If the dashboard still does not advance:

1. Run amics --version. If the command is missing, add ~/.local/bin to PATH or run the installer again.
2. Run amics login again and complete the browser authorization. A successful login connects the CLI to the workspace shown in the browser.
3. Run amics skill install --help to see supported agents, then rerun amics skill install. Reinstalling updates the canonical skill safely.
4. Use Check again in the dashboard. It continues retrying automatically after temporary control-plane or network failures.