CLI overview

The X4RGE CLI is how you run agents from a terminal — same company account, models, and project rules as the desktop app and cloud agents, but built for developers who already work in the shell, in scripts, or in CI.

Think of it as agents where your code already lives: you cd into a repo, describe what you want, and get output in the terminal (or a run ID for automation) — without opening a browser for every task.

This page explains what the CLI is, when to use it, and how it connects to the rest of X4RGE. Hands-on setup is Installation. Pipelines and bots are Headless & CI.

What this page is for

Who this page is for

You do not need to read command flags here — those live on 4rged.ai/cli/install.

What the CLI is and is not

Rule of thumb: use the CLI when the terminal or a pipeline is already where you work.

Understand the CLI at a glance

Conceptual flow (human on laptop):

1. Install + login once
2. cd into repo
3. Run with prompt (+ project if your org uses projects)
4. Read output in terminal — or hand off to cloud if the job is long

Where to go next

This overview stays conceptual. Follow the row that matches what you're doing today.

CLI vs desktop vs cloud

Choose by how you work, not by "most powerful":

Many teams use desktop for exploration and CLI in CI on the same repos — not either/or.

Choose local vs cloud

Same CLI entrypoint — different where work runs:

Both paths count toward Usage.

Login vs API key

Do not use login in CI — pipelines need a key in secrets.

Who can use the CLI

If Require project assignment is on in Settings, you need project membership before runs succeed — same as desktop.

Admins may restrict API keys; that blocks automation, not necessarily 4rged login locally.

Why the CLI matters

The CLI is for developers and automation — same permissions and spend as other surfaces.

How the CLI fits together

What a run looks like

On your laptop (typical):

1. Terminal open in repo
2. You run agent with a clear prompt
3. Agent reads/edits within policy
4. Output in terminal; you review before commit
5. Usage recorded under your org (and project if scoped)

In CI (typical):

1. Job installs pinned CLI
2. API key from secrets → whoami
3. Agent run → run ID + JSON
4. Job waits or polls → pass or fail on exit code

Details: Headless & CI.

In practice

Project-scoped runs

When work is organized in projects, pass project on CLI runs so:

• Repos and policy match desktop for that initiative
• Usage rolls up to the right project in Usage
• Tasks can link to agent runs — Tasks & views

If you see project or access errors: confirm Project members and linked GitHub repos.

Get started

1. Read this overview

   Decide CLI vs desktop vs cloud for your task.

2. Install and sign in

   Installation — 4rged login, not API key on day one.

3. Run from a repo

   Low-risk first prompt; add project if your team uses projects.

4. Automate later

   Headless & CI when you need pipelines — not before local works.

5. Go long in cloud

   Cloud agents when work outgrows one terminal session.

Fix common issues

1. Not installed

   Installation — PATH, new terminal.

2. Not signed in

   4rged login locally; API key in CI — Headless & CI.

3. Run denied

   Org + project + model policy.

4. Wrong directory

   Run from repo root, not home folder.

5. CI fails, local works

   Secrets, pinned version, project scope — Headless & CI.

6. Still stuck

   Troubleshooting or org admin.

Questions about the CLI?