Skip to main content

CLI installation

The 4RGE CLI installs from the terminal and authenticates against your 4RGE account. After sign-in, it shares your organization's access boundaries, model policy, and budget rules with the desktop and cloud surfaces.

Prerequisites

RequirementNotes
4RGE accountMember of an organization with agent entitlement
Supported OSmacOS, Linux, and Windows builds on the download page
Git repositoryLocal runs expect a git working tree (or explicit --repo path)
NetworkRequired for auth, policy fetch, and cloud handoff

Org admins may restrict personal API keys — if headless auth fails, ask an admin to enable keys in Settings or use interactive 4rged login locally.

Install and authenticate

  1. Install the CLI

    Install from 4rged.ai/cli/install for your platform:

    # macOS and Linux
curl -fsSL https://4rged.ai/cli/install | sh
 
# Verify
4rged --version

    On Windows, run the PowerShell installer from 4rged.ai/cli/install.ps1.

  2. Sign in interactively

    Run 4rged login and complete the browser flow at auth.4rged.ai. The CLI stores a session bound to your user and active organization.

    4rged login
4rged whoami
# org: acme-corp  role: member  surfaces: desktop, cli, cloud

  3. Configure headless credentials (optional)

    For scripts and CI, create a User API key from Dashboard → Integrations → User API Keys. Export it as an environment variable — never commit it to the repository.

    export X4RGE_API_KEY="x4rge_live_..."
4rged whoami

  4. Run from a repository

    cd into a linked project repo and start a local or cloud-backed run:

    cd ~/work/payments-api
4rged agent run --project pay-platform --prompt "Explain middleware chain"

What the install script does

The install script served from 4rged.ai/cli/install downloads a versioned tarball from the CLI release base (X4RGE_CLI_RELEASE_BASE_URL, default https://downloads.4rged.ai/cli), verifies the SHA-256 checksum, and installs the 4rged binary. By default it lands in ~/.local/bin on macOS and Linux (override with X4RGE_CLI_INSTALL_DIR). Pin a build with X4RGE_CLI_VERSION before running the script — for example X4RGE_CLI_VERSION=1.2.0 curl -fsSL https://4rged.ai/cli/install | sh.

Device sign-in

Interactive login uses the same auth gateway as the dashboard. The CLI opens a device-auth handoff at auth.4rged.ai/cli with a device code; after you approve in the browser, return to the terminal to continue. If sign-in fails, confirm auth.4rged.ai is reachable and that your account belongs to an organization with agent entitlement.

Verify policy before production use

After install, confirm the CLI sees the models and repos you expect:

  1. Check effective models

    4rged policy models --surface cli

    Lists allowed models for the CLI surface after org (and team/project) policy.

  2. Check repo access

    4rged policy repos --project pay-platform

    Shows linked repositories and enforcement mode (warn vs enforce) for hosted agents.

  3. Dry run

    4rged agent run --prompt "List top-level packages" --dry-run

    Validates auth, policy, and repo scope without consuming usage (when supported by your CLI version).

Updating and side-by-side versions

TaskCommand pattern
UpgradeRe-run the install script or package manager command from the download page
Pin version in CISet X4RGE_CLI_VERSION before install (see Headless & CI)
Clear stale session4rged logout then 4rged login
Note

Install commands are served from 4rged.ai/cli/install. Internal 4RGE orgs may use a separate build channel — follow your platform team's instructions.

API keys are secrets

User API keys grant programmatic access equivalent to your account for allowed surfaces. Store them in your CI secret manager, rotate on offboarding, and scope keys to the minimum org/project needed for the automation.

CLI overview

Command patterns and when to use local vs cloud runs.

Headless & CI

GitHub Actions and non-interactive authentication.