Ara CLI

Ara CLI is the local control surface. It signs you in, connects your coding agents to Ara, and installs the native worker that can run approved work on your own machine.

Install

$
curl -fsSL https://ara.so/install.sh | bash
$
export PATH="$HOME/.local/bin:$PATH"

The installer places a signed binary at ~/.local/bin/ara.

Sign in

$
ara login

Sign-in completes in the browser and binds the CLI to one workspace. The CLI keeps its own revocable grant, separate from the grants held by each coding client. You have 15 minutes to approve the request.

After you approve, the browser redirects to a local http://127.0.0.1:.../callback URL that hands the login back to your terminal. If that page cannot load — the browser is on another machine, or behind a proxy that cannot reach your loopback — copy the callback URL out of the address bar and paste it into the waiting ara login prompt to finish signing in. A callback URL only works in the ara login attempt that produced it; if the attempt has already exited, run ara login again.

Connect your coding agents

$
ara mcp setup
$
ara mcp status

This configures every supported client Ara detects and starts each one’s native OAuth flow. Use the command’s help output when you want to limit setup to specific detected clients. What each client receives, and which tools the connection exposes, is covered in Ara MCP.

Start a cloud session

$
ara run --repo acme/web -m "fix the failing CI"

Creates a cloud session on a connected repository and prints its URL. Options cover the same dials as the API: --provider, --model, and --effort.

Session environment variables

A session can carry its own environment, visible to that session only. It overrides repository and account secrets of the same name, follows the session across follow-up messages, and is never written to your organization’s secret stores. Same field on the API: env on create session.

$
# forward secrets from a secret manager, per session, without storing them in Ara
$
infisical run -- ara run --repo acme/web --pass-env AXIOM_TOKEN -m "..."
$
$
# -e NAME forwards one var from your shell; -e K=V sets a value inline
$
ara run --repo acme/web -m "..." -e DATABASE_URL -e DEBUG=1
$
$
# or read a dotenv-style file
$
ara run --repo acme/web -m "..." --env-file .env.session

For secret values, prefer the forwarding forms (-e NAME, --pass-env, --env-file): an inline -e K=V value is visible to local process listings and shell history like any command-line argument. Values are sent once in the create request, stored encrypted, never returned by the CLI or any read endpoint, and redacted from logs and transcripts.

Two composition notes: in infisical run --env=dev, --env selects Infisical’s environment slug, while in ara run it sets a variable, and the K=V shape keeps the two from colliding. --env-file reads plain dotenv files, including infisical export --format=dotenv or dotenv-export output (not dotenv-eval). On a name collision, files apply first, then forwarded vars, then inline -e K=V, so the most explicit source wins.

Run work on this Mac

$
ara device

Bare ara device installs or repairs this Mac as a background Ara Device, and is idempotent: running it again on the same version changes nothing. The signed worker updates its own managed runtime, health-checks the active release, and rolls back a failed activation.

Ara Device is an execution target for a session, not a separate product. You start the session in Ara Cloud and choose this Mac as where it runs. Approved file and shell operations execute locally; the transcript stays in Ara Cloud.

To connect a Mac from the web app instead, open Workspace → Devices, choose Copy Ara CLI setup on the Add a Mac card, and complete the browser approval.

Keys for CI

Interactive coding agents should use OAuth. For unattended CI or headless jobs, create a scoped ara_ API key and store it in that job’s secret manager. See the API quickstart.