CLI overview

The 4RGE CLI is a terminal-first way to run agents. It is designed for developers who want a fast path for local agent runs, scripted workflows, and CI — keeping output scriptable and work close to the repository. The CLI uses the same account boundary, model catalog, and budget policy as the desktop app and cloud agents.

What the CLI is for

The CLI can start local runs (against your working tree) or hand off to cloud-backed runs for longer tasks — same entrypoint, different runtime target.

Surfaces and policy

Every CLI run resolves effective policy from your organization:

org model catalog → team/project overrides → member exceptions → contract ceiling

Runs respect model control defaults for the CLI surface unless you override with an allowed model flag. Spend rolls up to Usage & billing under the same Included / On-demand buckets as desktop and cloud.

Installation and binary

Install the 4RGE CLI from 4rged.ai/cli/install (bash) or 4rged.ai/cli/install.ps1 (Windows). The installed binary is named 4rged. Pin versions in automation with X4RGE_CLI_VERSION — see Installation and Headless & CI.

Authentication surfaces

Interactive use starts with 4rged login, which opens a device-auth handoff at auth.4rged.ai/cli (the same auth gateway as the dashboard). Headless use relies on User API keys created under Dashboard → Integrations → User API Keys and exported as X4RGE_API_KEY. Both paths bind the CLI to your organization boundary before any agent run.

Common command patterns

Exact flags evolve with CLI releases; patterns below are stable conventions. Refer to the CLI product/download page for the current command tree.

Authentication

# Interactive sign-in (binds CLI to your org)
4rged login
 
# Verify account and org context
4rged whoami
 
# Headless: User API key from Dashboard → Integrations
export X4RGE_API_KEY="x4rge_live_..."
4rged whoami

Agent runs

# Local run from repo root
4rged agent run --prompt "Add input validation to POST /users"
 
# Scoped to a project (usage + repo policy)
4rged agent run \
  --project atl-platform \
  --prompt "Fix flaky test TestAuthRefresh"
 
# Machine-readable output for scripts
4rged agent run \
  --prompt "Summarize diff vs main" \
  --output json
 
# Cloud handoff for long work
4rged agent run \
  --cloud \
  --prompt "Migrate package foo to bar across the monorepo"

Inspecting runs

# Poll status by run ID (from json output or CI artifact)
4rged agent status --run run_01H...
 
# Fetch summary when complete
4rged agent show --run run_01H... --output json

When to prefer CLI vs desktop vs cloud