Headless & CI

When a person runs the CLI, they use 4rged login on a laptop — browser sign-in, then commands from a repo. When a pipeline runs the CLI, there is no browser: the job uses a User API key stored as a CI secret, installs the CLI, runs the agent, and passes or fails the build from the result.

That second pattern is headless — the same X4RGE agents and org rules as desktop, but built for GitHub Actions, GitLab CI, cron, and internal bots.

This page is for teams wiring the CLI into automation. For a first install on your machine, see Installation. For when to use the CLI at all, see CLI overview.

What this page is for

You want to…	Headless & CI helps you…
Understand headless	Run agents without a human at the keyboard
Authenticate in CI	API keys in secrets — not browser login
Gate merges on agent results	Exit codes and structured output
Track automated runs	Run IDs for polling and artifacts
Keep pipelines stable	Pin CLI version so jobs do not drift
Pick local vs cloud in CI	Short work on the runner; long work in cloud
Stay within company policy	Same models, budgets, and repos as desktop

No CI bypass

Automation uses your organization's model control and usage. Denied models and budget stops fail the job — same as for a developer on a laptop.

Who this page is for

You are…	Start here
Developer adding a bot to one repo	Set up for CI → Typical pipeline flow
Platform / DevOps rolling out org-wide	For org admins + pin version + key rotation
Org admin enabling keys and budgets	Rules that still apply + Settings
PM / lead wondering if CI fits	Headless vs cloud automations

You do not need to be an org admin to run headless on a single repo — you need a key, a secret, and access to the project.

Understand headless at a glance

Term	Plain meaning	Example
Headless run	CLI started by a script or CI job	GitHub Action on every PR
User API key	Long-lived secret for automation	Created in dashboard → Integrations
CI secret	Encrypted store for the key	`X4RGE_API_KEY` in GitHub Secrets
Structured output	Machine-readable result	JSON with run ID and status
Run ID	Reference until the agent finishes	Poll or upload as artifact
Pinned CLI version	Fixed install in every job	`1.2.0` until you bump it deliberately
Exit code	How CI knows pass vs fail	`0` = success; non-zero fails the job

First time wiring CI — typical order:

Create API key (dashboard)
Save as CI secret (never in git)
Add job steps: install CLI (pinned) → whoami → agent run
Optional wait step for long or cloud runs
Fail the job on error; store JSON summary if useful
Ask admin to link repo on the project if policy errors appear

Command flags change over time — 4rged.ai/cli/install has the current reference. This page explains concepts that stay stable.

	Interactive	Headless
Where	Your laptop	CI, cron, server bot
Sign-in	`4rged login` + browser	API key in secrets
Doc	Installation	This page
Rotate when	New machine / sign out	Offboarding, leak, quarterly
Works in GitHub Actions?	No — no browser	Yes

Never commit secrets

API keys belong in GitHub Secrets, GitLab protected variables, or a vault — never in the repository, workflow files, or log output.

Headless vs cloud automations

Both can run agents without a person watching — choose by who owns the trigger:

	Headless CLI in CI	Cloud automations
Triggered by	Your pipeline (PR, schedule, manual workflow)	Events and rules in X4RGE cloud
Runs on	CI runner (install CLI each job)	X4RGE cloud runtime
Best for	"Run agent as part of this build"	"When X happens, start agent in cloud"
You manage	YAML, secrets, pinned CLI	Automation config in product

Many teams use CLI in CI for PR checks and cloud automations for ongoing monitors — not either/or.

Choose local vs cloud in CI

Same CLI command — different where the work runs:

Run in CI…	When to choose it
Local (on the CI runner)	Short prompts — review diff, lint summary, small fix attempt
Cloud handoff	Long generation, large refactors, jobs that exceed runner timeout

Signal	Action
Job times out	Add wait timeout or switch to cloud
Runner cost is high	Offload long work to Cloud agents
Need result in same job	Prefer local if it finishes within limits

Why headless matters

Without headless CLI	With headless CLI
Agents only when someone is at a laptop	PRs and schedules trigger agents automatically
Manual copy-paste of agent output	JSON and run IDs for the next pipeline step
No merge gate on agent review	Pipeline fails when policy or agent fails
Fragile "latest CLI" installs	Pinned version — predictable behavior
Ad hoc personal keys in scripts	Documented secret + rotation

How headless fits together

Piece	Role	Learn more
API key	Proves identity in CI	Set up for CI
CLI install	`4rged` on the runner	Installation
Project scope	Repos, policy, usage	Projects overview
Agent run	Prompt → work → output	CLI overview
Run ID / exit code	Pass or fail the job	What success looks like
Cloud handoff	Long work off the runner	Cloud agents
Alternative	Event-driven cloud	Cloud automations

How automation works

Piece	Why it matters
Scriptable output	Next step reads run ID, summary, or PR link
Run ID	Poll, artifact upload, trace in Usage
Exit code	Standard CI pass/fail — non-zero on policy or agent error
Project flag	Same repos and rules as desktop for that initiative
Task link (optional)	Tie run to Tasks & views

One-line flow: install → verify key → agent run → (wait) → pass or fail.

Set up for CI

Create a User API key
Dashboard → Integrations → User API keys. If missing, an org admin enables keys in Settings.
Store as a CI secret
Name it clearly (e.g. X4RGE_API_KEY). Map into the job environment. Never log the value.
Install pinned CLI in the job
Same installer as Installation, with a fixed version — see Pin the CLI version.
Verify before heavy runs
Run 4rged whoami (or JSON variant) so bad keys fail in seconds, not after a long agent run.
Run with project + clear prompt
Use your project slug when the org scopes repos. Write a prompt the job can repeat safely (review rules, doc sync scope, etc.).

Use a bot or service account when possible

A dedicated automation user (not a personal developer key) simplifies rotation and audit when someone leaves the team.

Typical pipeline flow

Same shape for GitHub Actions, GitLab, Jenkins, or other CI:

Checkout
Clone the repo the agent should read or modify.
Install CLI
Pinned version your platform team approved.
Authenticate
Inject secret; confirm org with whoami.
Run agent
Focused prompt; project + json output when scripts parse the result.
Wait (if needed)
Local runs may finish inline; cloud or long runs need poll/wait by run ID with a timeout.
Gate
Non-zero exit fails the pipeline; optional artifact or PR comment from JSON summary.

Full provider YAML samples live in hidden operator notes and on the install page — adapt steps above to your provider's syntax.

What success looks like

Outcome	What it means for the team
Job green, exit 0	Agent completed; policy allowed models and repos
Job red, policy error	Model, budget, or repo blocked — fix config, not the prompt
Job red, agent error	Agent failed task — treat like a failed test; review logs
JSON artifact saved	Debugging and audit without re-running the agent
Run ID in logs	Trace spend and history in Usage

A healthy pipeline fails loudly on policy problems so bad merges do not slip through.

Pin the CLI version

Problem with "always latest"	Benefit of pinning
Job breaks with no app code change	Upgrades are deliberate
Flags differ between branches	Same behavior on main and PRs
Hard to reproduce locally	Match pinned version on a dev machine

Pick a version your org tested; bump it in one test pipeline before company-wide rollout. Version env details are on the install page and in operator notes below.

Rules that still apply

Control	What happens in CI
Model control	Disallowed model → job fails with policy message
Usage / budget	Hard/soft stop may block or warn
Project + repo link	Unlinked repo may fail when enforcement is strict
Membership	API key user must access the project

Check Dashboard → Usage for denial hints; confirm repos on the project.

For org admins

Before enabling CI for many teams:

Step	Action
CLI models	Sensible default for CLI in Model control
Budget	Warn vs stop for automation that could use on-demand capacity
Projects	CI repos linked to the right projects
Keys	Enable API keys; document rotation; revoke on offboarding
Ownership	Name who owns the org CI secret and approved CLI version
Alternative	Consider Cloud automations for always-on monitors

In practice

You want to…	Do this
Agent review on every PR	Secret + pinned install + review prompt + fail on error
Nightly doc sync	Scheduled job; cloud if generation is long
Block merge on agent failure	Rely on exit code; store JSON artifact for reviewers
Link to Jira-style tickets	Pass task context — Tasks & views
Save CI runner minutes	Cloud for multi-hour work
Debug "it worked yesterday"	Check unpinned CLI, revoked key, budget stop
Avoid maintaining YAML	Evaluate Cloud automations

Fix CI issues

Fails on first step (auth)
Wrong secret name, revoked key, or keys disabled in Settings — recreate and update CI.
whoami OK but agent denied
Model not allowed, budget stop, or missing project access for key user.
Repo / project error
Link repo on project; verify project slug matches GitHub integration.
Job hangs
Add timeout on wait; use cloud for long runs.
Flaky without code changes
Unpinned CLI upgraded — pin version and retest.
Key person left company
Rotate API key; update CI secret; revoke old key in Integrations.
Still stuck
Troubleshooting or org admin.

Questions about headless and CI?

Question	Answer
What does headless mean?	CLI runs in automation without browser login
Can I use `4rged login` in CI?	No — use an API key
Where do I put the key?	CI secrets / vault — never in git
Who creates keys?	Usually each user; admins may restrict
Does CI usage bill like desktop?	Yes — Usage
GitHub vs GitLab?	Same CLI; only secret syntax differs
Local or cloud in CI?	Short = local runner; long = cloud handoff
Headless vs cloud automations?	CI owns trigger vs X4RGE event rules — see above
Where are YAML examples?	Install page + hidden operator section
How often rotate keys?	Offboarding, leak, or quarterly
Can I run CI without a project?	Depends on org; most teams pass project for policy
What if the job is green but wrong?	Tighten prompt, add review step, fail on JSON fields

CLI overview

Local vs cloud and project-scoped runs.

CLI installation

Interactive install and first run on a laptop.

Cloud automations

Event-driven cloud runs without heavy CI YAML.

Troubleshooting

Auth, policy, and run failures.

Headless & CI

What this page is for

Who this page is for

Understand headless at a glance

Headless vs interactive login

Headless vs cloud automations

Choose local vs cloud in CI

Why headless matters

How headless fits together

How automation works

Set up for CI

Create a User API key

Store as a CI secret

Install pinned CLI in the job

Verify before heavy runs

Run with project + clear prompt

Typical pipeline flow

Checkout

Install CLI

Authenticate

Run agent

Wait (if needed)

Gate

What success looks like

Pin the CLI version

Rules that still apply

For org admins

In practice

Fix CI issues

Fails on first step (auth)

whoami OK but agent denied

Repo / project error

Job hangs

Flaky without code changes

Key person left company

Still stuck

Questions about headless and CI?