Skip to main content

CLI installation

Getting started with the CLI is three moves on your machine: install the 4rged command, sign in with your company account, and run an agent from a git repo you already use for development. After that, the CLI shares the same organization, models, and usage rules as the desktop app and cloud agents.

This page is the hands-on setup guide for your laptop. For why you'd use the CLI at all, see CLI overview. For pipelines and bots (no browser login), see Headless & CI.

What this page is for

You want to…This page helps you…
Install once on your machinemacOS, Linux, or Windows
Sign in the right wayBrowser login for daily dev — not CI secrets
Run a safe first agentSmall prompt from a real repo checkout
Know you're doneChecklist before daily use or before wiring CI
Fix setup problemsPATH, login, org access, policy errors
Skip ahead to automationPointer to API keys → Headless & CI
Flags live on the install page

4rged.ai/cli/install has the latest commands. This doc teaches the setup flow most developers follow — not every advanced install option.

Who this page is for

You are…Focus on
New developer on the teamThe three-step setup → Run your first agent
Developer who installed but auth failsSign in + Fix install issues
Platform engineer prepping CIInstall here once locally, then Headless & CI for keys
Contractor with org inviteAccept invite in dashboard beforewhoami shows your org

You do not need the desktop app to complete this page — CLI only is fine.

Understand installation at a glance

TermPlain meaningExample
4rgedThe CLI command after install4rged --version
Install scriptOne-line download from X4RGEcurl on Mac/Linux; PowerShell on Windows
Interactive loginBrowser approval for your laptop4rged login
SessionCLI remembers you until logoutNo login every command
Repo rootFolder where you run the agentYour normal git clone directory
Project scopeWhich X4RGE project applies--project your-project
API keyFor scripts/CI only — not first-day setupHeadless & CI

Typical first day:

  1. Install → 4rged --version works
  2. Login → browser → 4rged whoami shows your org
  3. cd into repo → one read-only agent prompt
  4. If denied → check project membership or ask admin

Before you install

You need…Why
X4RGE account in an orgInvited by admin — accept invite in dashboard first
macOS, Linux, or WindowsInstallers on 4rged.ai/cli/install
InternetDownload, login, policy
Git repositoryLocal runs use your checkout
Project access (often)Org may require project membership to run agents

Org admins may disable API keys later — that does not block interactive 4rged login on your machine.

The three-step setup

StepWhat you doSuccess signal
1. InstallRun platform installer4rged --version prints a version
2. Sign in4rged login + browser4rged whoami shows your org
3. First runcd to repo + simple promptOutput in terminal or clear policy error

Skip API keys until you need CI — Login vs API key below.

Install the CLI

  1. macOS or Linux

    curl -fsSL https://4rged.ai/cli/install | sh
4rged --version

    If 4rged is not found: restart the terminal or add the install directory to PATH (default path is on the install page).

  2. Windows

    Run 4rged.ai/cli/install.ps1 in PowerShell, open a new terminal, then:

    4rged --version

  3. Need options or mirrors?

    Open 4rged.ai/cli/install in a browser for guided steps and current platform notes.

Install once per machine

Re-run the same installer to upgrade later — see Update or reinstall.

Sign in

Interactive sign-in is for you at the keyboard — one browser step, then the CLI reuses the session.

  1. Login

    4rged login

    Approve access in the browser when prompted.

  2. Verify

    4rged whoami

    Expect your user and organization. Wrong org? Switch org in the dashboard, then 4rged logout and login again.

  3. Logout (shared machines)

    4rged logout
Company account required

Use the account your admin invited. A personal account with no org cannot run agents even if install succeeded.

Login vs API key

Easy to mix up when reading docs:

Login (4rged login)API key
ForYour laptop, daily devCI, cron, scripts
HowBrowser once per sessionSecret in dashboard → env / CI
This page?Yes — Sign inOptional — skip until Headless & CI
In GitHub Actions?NoYes

First-time setup: login only. Add API keys when you automate.

Run your first agent

  1. Go to your repo

    cd path/to/your-project

    Same folder you use for git status — not your home directory.

  2. Add project (if your team uses projects)

    Ask your lead for the project slug. It aligns repos, model policy, and usage with the desktop app.

  3. Run something low-risk

    Without project:

    4rged agent run --prompt "Summarize the main packages in this repo"

    With project (replace name):

    4rged agent run --project your-project --prompt "Summarize the main packages in this repo"

  4. Read the result

    Output appears in the terminal. For longer work, see local vs cloud in CLI overview.

First run = learn policy

Start with read-only prompts (summarize, explain) until you know which models and repos your org allows.

What success looks like

After…Good sign
Install4rged --version works in a new terminal
Loginwhoami shows correct org name
First runSummary text in terminal or clear message ("model not allowed", "not on project")
Wrong outcomeUse Fix install issues — a clear policy error is still useful

You're ready for daily CLI use when install, login, and one simple run all behave predictably.

Optional: API key for scripts

Skip this until you need automation:

  1. Dashboard → Integrations → User API keys
  2. Store in CI secrets or a vault — never in git
  3. Headless & CI for pipelines
Keys are secrets

Rotate when someone leaves; treat like a password.

Confirm you are ready

Before daily use or copying setup into CI:

CheckGood looks like
Version4rged --version OK
Accountwhoami → expected org
ProjectYou're on Project members if required
DirectoryCommands run from repo root
PolicyFirst agent run works or fails with understandable policy text
Next stepCLI overview for local/cloud; Headless for CI

How installation fits together

StepConnects to
InstallCLI overview — what you'll run
LoginDashboard members — org invite
Project scopeProjects overview
First runModel control, Usage
CI laterHeadless & CI
ProblemsTroubleshooting

Update or reinstall

TaskAction
UpgradeRe-run installer from 4rged.ai/cli/install
Stale session4rged logout → 4rged login
CI pin versionHeadless & CI — not needed for local dev only
Private install channel

Some companies use an internal build. Follow platform team docs if the public installer is not for you.

Fix install issues

  1. `4rged`: command not found

    New terminal window; check PATH on install page.

  2. Login / browser problems

    Try another browser; check VPN/proxy; confirm you can open X4RGE auth in browser.

  3. whoami: no org or wrong org

    Accept org invite (Members); switch org in dashboard; logout + login.

  4. Agent run denied

    Project members; Model control; Require project assignment in Settings.

  5. Works locally, fails in CI

    CI needs API key — not login. See Headless & CI.

  6. Still stuck

    Troubleshooting or org admin.

Questions about installation?

QuestionAnswer
Where do I download?4rged.ai/cli/install
Command name?4rged
Need API key on day one?No — login first
Windows supported?Yes — PowerShell installer
Need desktop app?No
Why --project?Same repos/policy/usage as desktop for that initiative
Invited but whoami empty?Accept invite in dashboard first
Install OK but agent blocked?Usually project or model policy — not install
CI setup?Headless & CI
Same CLI for cloud runs?Yes — cloud is a run option (CLI overview)
How long does login last?Until logout or session expires — then login again
CLI overview

After install — local vs cloud and project scope.

Headless & CI

When you're ready for pipelines and API keys.

Projects overview

Link repos and scope runs.

Troubleshooting

Auth, policy, and run failures.