CLI Command Reference

Global Options

Flag	Description
`--version`, `-v`	Print the CLI version
`--help`, `-h`	Show help for any command
`--debug`, `-d`	Use local-debug mode (plaintext output, for debugging)

agentrix start

Start the daemon if it is not already running, then show its status.

agentrix start

What it does:

Authenticates (browser OAuth on first run, or validates existing credentials).
Checks critical dependencies (git, sandbox tools). Exits if any are missing.
Spawns the daemon as a detached background process.
Waits up to 5 seconds for the daemon to report ready.
Prints daemon status.

agentrix start does not perform CLI upgrade checks. Use agentrix upgrade for manual CLI upgrades, or trigger upgrade-cli from an app machine-control surface where available.

Example:

Starting Agentrix background service...
✓ Daemon started successfully

🤖 Daemon Status
✓ Daemon is running
  PID: 12345
  Started: 4/22/2026, 10:00:00 AM
  CLI Version: 1.2.3
  HTTP Port: 51234

agentrix stop

Stop the running daemon.

agentrix stop

Any active worker sessions are terminated when the daemon stops.

agentrix status

Show daemon and authentication status.

agentrix status

This is equivalent to running agentrix doctor filtered to daemon + auth sections.

Example output:

🤖 Daemon Status
✓ Daemon is running
  PID: 12345
  Started: 4/22/2026, 10:00:00 AM
  CLI Version: 1.2.3
  HTTP Port: 51234

🔐 Authentication
✓ Authenticated (credentials found)

agentrix doctor

Full system diagnostics — version, configuration, environment variables, authentication, dependencies, and daemon status.

agentrix doctor

Use this as the first step when troubleshooting. It shows:

CLI version, platform, Node.js version
Daemon spawn paths (wrapper script, entrypoint)
Configuration (home dir, server URL, log dir)
Environment variables that affect Agentrix behavior
Authentication status
Dependency status (git, claude, codex, sandbox tools)
Daemon status (running / stale / not running)

agentrix llm-config apply

Generate Claude Code, Codex, and Gemini config from Agentrix environment variables. The CLI Docker image runs this command automatically before agentrix daemon or agentrix start; local and systemd deployments can run it manually.

export AGENTRIX_BASE_URL=https://api.xmz.ai
export AGENTRIX_API_KEY=<llm-gateway-api-key>

agentrix llm-config apply --verbose

For this command, AGENTRIX_API_KEY and AGENTRIX_BASE_URL point to the LLM gateway. agentrix-run also reads variables with those names, but there they mean Agentrix API options; see agentrix-run.

By default, the command writes only missing config files and leaves existing files alone. Codex config stays minimal; worker launch options control runtime sandboxing and approval policy.

Options:

Option	Description
`--source env`	Read config from environment variables. Only `env` is supported
`--force`	Overwrite existing Claude, Codex, PI, and Gemini config files
`--dry-run`	Show planned file writes without changing disk state
`--verbose`	Print each config file action

Related env vars:

Variable	Default	Description
`AGENTRIX_API_KEY`	—	LLM gateway key
`AGENTRIX_API_KEY_FILE`	—	Read the LLM gateway key from a file
`AGENTRIX_BASE_URL`	`https://api.xmz.ai`	LLM gateway URL; Codex uses `/v1` under this URL
`AGENTRIX_CLAUDE_HOME`	`~/.claude`	Claude Code config directory
`AGENTRIX_CODEX_HOME`	`~/.codex`	Codex config directory
`AGENTRIX_PI_HOME`	`~/.pi/agent`	PI config directory; `PI_CODING_AGENT_DIR` is also supported
`AGENTRIX_GEMINI_HOME`	`$AGENTRIX_HOME_DIR/config/gemini`	Gemini config directory
`AGENTRIX_CODEX_MODEL`	`gpt-5.5`	Default Codex model
`AGENTRIX_PI_MODEL`	Same as `AGENTRIX_CODEX_MODEL`	Default PI model
`AGENTRIX_CLAUDE_MODEL`	`claude-sonnet-4-6`	Default Claude model
`AGENTRIX_CLAUDE_FAST_MODEL`	`claude-haiku-4-5`	Claude fast model
`AGENTRIX_CLAUDE_SUBAGENT_MODEL`	Same as `AGENTRIX_CLAUDE_MODEL`	Claude subagent model
`AGENTRIX_GEMINI_IMAGE_MODEL`	`gemini-2.5-flash-image`	Gemini image model

agentrix upgrade

Upgrade the CLI to the latest version on npm.

agentrix upgrade

This runs npm install -g @agentrix/cli@latest and:

Also checks for agent updates (companion, etc.).
Restarts the daemon automatically if it was running.

agentrix start does not perform automatic CLI upgrade checks.

agentrix logout

Unbind this machine from your Agentrix account.

agentrix logout

Removes ~/.agentrix/credentials.json. The next agentrix start will open the browser authentication flow again.

agentrix ls

List sessions currently tracked by the running daemon.

agentrix ls

Each session corresponds to a running or recently-started worker process.

Example:

Active sessions:
[
  {
    "taskId": "task-abc123",
    "pid": 54321,
    "startedBy": "cli"
  }
]

Returns No active sessions if no workers are running.

agentrix kill <sessionId>

Stop a specific worker session by its task ID.

agentrix kill task-abc123

agentrix killall

Terminate all runaway agentrix processes found on the system.

agentrix killall

Use this when sessions are stuck or the daemon state is inconsistent. Reports how many processes were killed.

agentrix git-server add

Add a private GitLab server to the local daemon config and store the PAT used to access it. User identity binding and proxy registration are independent choices.

agentrix git-server add \
  --base-url https://gitlab.example.com

Options:

Option	Description
`--base-url <url>`	GitLab site URL, for example `https://gitlab.example.com`
`--api-url <url>`	GitLab API URL. Defaults to `<base-url>/api/v4`
`--pat-file <file>`	Read the PAT from a file; use `-` to read from stdin
`--bind-user` / `--no-bind-user`	Whether to bind the GitLab account to the current Agentrix user; pressing Enter at the prompt defaults to no binding
`--proxy` / `--no-proxy`	Whether to register this machine as a Git proxy node; prompts by default

When --pat-file is omitted, the command prompts for the PAT interactively without echoing it.

printf '%s' "$GITLAB_PAT" | agentrix git-server add \
  --base-url https://gitlab.example.com \
  --pat-file -

The command prints JSON with webhookUrl and webhookSecret. The PAT and webhook secret are encrypted under ~/.agentrix/credentials/; baseUrl and apiUrl are stored as local config.

The prompt defaults to no binding, which is appropriate for a shared bot PAT on a Private Cloud machine. The daemon still validates and stores the PAT locally, but does not send it to the Agentrix API or create user-scoped GitLab credentials, identities, or repositories. Pass --bind-user only when the PAT represents the current Agentrix user. --proxy remains independent and can expose the machine's GitLab network access without treating the bot as the current user's identity.

This command requires a bound machine. If it reports that the Agentrix auth secret is missing, run agentrix start first.

agentrix git-server list

List private GitLab config stored on this machine.

agentrix git-server list

The output includes the full local view: Git server ID, baseUrl, apiUrl, webhook endpoint, current daemon webhookUrl, whether a PAT is configured, PAT user metadata, webhookSecret, and cached project-level pipeline trigger tokens.

[
  {
    "id": "corp-gitlab",
    "type": "gitlab",
    "baseUrl": "https://gitlab.example.com",
    "apiUrl": "https://gitlab.example.com/api/v4",
    "webhookEndpointPath": "/webhooks/gitlab/corp-gitlab",
    "webhookUrl": "http://192.168.1.10:30624/webhooks/gitlab/corp-gitlab",
    "patConfigured": true,
    "patMeta": {
      "username": "alice",
      "email": "[email protected]",
      "lastValidatedAt": "2026-04-27T05:00:00.000Z",
      "expiresAt": null
    },
    "webhookSecret": "...",
    "projectTriggerTokens": {}
  }
]

If the daemon is not running, webhookUrl may be empty; run agentrix start and list again.

GitLab Webhook Setup

The daemon's built-in web server can receive GitLab webhooks directly and convert supported events into GitLab pipeline triggers.

Basic setup:

Run agentrix start to make sure the daemon is running.
Run agentrix git-server add to save the GitLab baseUrl, apiUrl, and PAT.
Run agentrix git-server list, then copy webhookUrl and webhookSecret.
In the GitLab project's Webhooks page, paste webhookUrl into URL and webhookSecret into Secret token, and select the event types that should trigger pipelines.
If GitLab is not on the same machine, enable daemonControl.allowLanAccess in ~/.agentrix/settings.json and restart the daemon.

{
  "daemonControl": {
    "allowLanAccess": true
  }
}

Supported Events and Mapping

The daemon webhook endpoint validates GitLab's X-Gitlab-Token, normalizes supported events, and triggers GitLab pipelines. It does not forward GitLab webhook payloads to the Agentrix repository inbox side channel.

Pipeline triggers default to all supported normalized events:

GitLab webhook	Pipeline result	Normalized event
`event_type: "issue"` or `object_kind: "issue"`	Triggers a project pipeline	`GITLAB_BRIDGE_EVENT_NAME=issues`, `GITLAB_BRIDGE_EVENT_ACTION=<github_action>`
`merge_request`	Triggers a project pipeline	`GITLAB_BRIDGE_EVENT_NAME=pull_request` or `pull_request_review`, `GITLAB_BRIDGE_EVENT_ACTION=<github_action>`
Non-system issue/MR `note` comments	Triggers a project pipeline	`GITLAB_BRIDGE_EVENT_NAME=issue_comment` or `pull_request_review_comment`, `GITLAB_BRIDGE_EVENT_ACTION=created/edited/deleted`
`pipeline`	Triggers a project pipeline	`GITLAB_BRIDGE_EVENT_NAME=workflow_run`, `GITLAB_BRIDGE_EVENT_ACTION=requested/in_progress/completed`
System `note`, GitLab-only changes, and other unsupported events	Does not trigger a pipeline; response body is `status: "ignored"` with a reason	Not applicable

Common normalized actions:

GitLab signal	Normalized event
Issue open/reopen/close	`issues.opened/reopened/closed`
Issue label added/removed	`issues.labeled/unlabeled`, one event per label
MR open/reopen/close/merge	`pull_request.opened/reopened/closed`, with `GITLAB_BRIDGE_PULL_REQUEST_MERGED=true` for merges
MR source/head update	`pull_request.synchronize`
MR reviewer added/removed	`pull_request.review_requested/review_request_removed`
Issue/MR ordinary comment	`issue_comment.created/edited/deleted`
Pipeline created/pending/running	`workflow_run.requested/in_progress`; `created` is exposed as `GITLAB_BRIDGE_WORKFLOW_RUN_STATUS=pending`
Pipeline success/failed/canceled/skipped	`workflow_run.completed`, with `GITLAB_BRIDGE_WORKFLOW_RUN_CONCLUSION` carrying the result

The bridge's default pipeline variables use the GITLAB_BRIDGE_* prefix. Agentrix also appends AGENTRIX_GIT_SERVER_ID so agentrix-run can resolve the configured private GitLab server.

Every daemon-triggered pipeline receives these base variables:

Variable	Meaning
`GITLAB_BRIDGE_EVENT_NAME`	normalized event name, for example `issues`, `pull_request`, `issue_comment`, or `workflow_run`
`GITLAB_BRIDGE_EVENT_ACTION`	Normalized event action
`GITLAB_BRIDGE_REPOSITORY`	Full repository path, for example `group/subgroup/repo`
`GITLAB_BRIDGE_REPOSITORY_OWNER`	`project.path_with_namespace` without the final path segment; subgroups are preserved
`GITLAB_BRIDGE_REF_NAME`	Target ref for the triggered pipeline
`AGENTRIX_GIT_SERVER_ID`	Git server ID configured on this machine

Event-specific variables are added as follows:

Event	Additional variables
`issues`	`GITLAB_BRIDGE_ISSUE_NUMBER`, `GITLAB_BRIDGE_ISSUE_TITLE`, `GITLAB_BRIDGE_ISSUE_URL`, plus `GITLAB_BRIDGE_LABEL_NAME`, `GITLAB_BRIDGE_LABELS`, `GITLAB_BRIDGE_LABELS_JSON`, and `GITLAB_BRIDGE_LABEL_CHANGES_JSON` for label events
`pull_request` / `pull_request_review`	`GITLAB_BRIDGE_PR_NUMBER`, `GITLAB_BRIDGE_HEAD_REF`, `GITLAB_BRIDGE_BASE_REF`, `GITLAB_BRIDGE_PR_TITLE`, `GITLAB_BRIDGE_PR_BODY`, `GITLAB_BRIDGE_PR_URL`, `GITLAB_BRIDGE_LABELS`, `GITLAB_BRIDGE_LABELS_JSON`, plus `GITLAB_BRIDGE_HEAD_SHA` and `GITLAB_BRIDGE_OLD_HEAD_SHA` for synchronize events when GitLab provides commit data
`issue_comment` / `pull_request_review_comment`	`GITLAB_BRIDGE_COMMENT_BODY`, `GITLAB_BRIDGE_COMMENT_ID`, `GITLAB_BRIDGE_COMMENT_URL`, plus either `GITLAB_BRIDGE_ISSUE_NUMBER` or `GITLAB_BRIDGE_PR_NUMBER` depending on the comment target
`workflow_run`	`GITLAB_BRIDGE_WORKFLOW_RUN_STATUS`, `GITLAB_BRIDGE_WORKFLOW_RUN_CONCLUSION`, `GITLAB_BRIDGE_WORKFLOW_RUN_ID`, `GITLAB_BRIDGE_WORKFLOW_RUN_NUMBER`, `GITLAB_BRIDGE_WORKFLOW_RUN_URL`, `GITLAB_BRIDGE_WORKFLOW_RUN_REF`, `GITLAB_BRIDGE_WORKFLOW_RUN_SHA`, and `GITLAB_BRIDGE_PR_NUMBER` when an MR can be inferred

Optional variables are present only when GitLab includes the matching payload field:

Variable	Meaning
`GITLAB_BRIDGE_ISSUE_TITLE`	Issue title; present when GitLab includes it in the payload
`GITLAB_BRIDGE_ISSUE_URL`	Issue URL; uses the payload URL first, then falls back to project URL plus IID
`GITLAB_BRIDGE_OLD_HEAD_SHA`	Previous MR head revision for `pull_request.synchronize` when GitLab provides it
`GITLAB_BRIDGE_HEAD_SHA`	Current MR head SHA for `pull_request.synchronize` when GitLab provides it

Notes:

The webhook URL is only the daemon endpoint. It does not contain the PAT, API URL, or pipeline trigger token.
The webhook secret is matched against GitLab's X-Gitlab-Token request header.
Pipeline trigger tokens are GitLab project-level tokens. The daemon creates or reuses a GitLab webhook bridge trigger the first time it handles a webhook for a project, then encrypts the token locally.
Delivery identity is read from GitLab's stable delivery headers (webhook-id, Idempotency-Key, X-Gitlab-Webhook-UUID, X-Gitlab-Event-UUID, then legacy X-Gitlab-Delivery). If none is present, the daemon uses a stable payload hash.
Successfully delivered normalized fan-out events are de-duplicated for repeated delivery attempts. Duplicate redeliveries return status: "ignored" with delivery reason: "duplicate_delivery_event"; failed fan-out events are not marked as processed, so a later manual redelivery can compensate them.
If GitLab rejects the pipeline trigger, for example because .gitlab-ci.yml is missing, the daemon logs the failure and returns HTTP 200 to GitLab with response body status: "failed". This avoids GitLab retrying a business-level failure. Non-200 webhook responses are reserved for requests the bridge cannot safely process, such as an invalid secret or missing local GitLab bridge configuration.

Environment Variables

These variables modify CLI behavior without changing settings.json.

Variable	Default	Description
`AGENTRIX_HOME_DIR`	`~/.agentrix`	Root state directory
`AGENTRIX_SERVER_URL`	`https://agentrix.xmz.ai`	Backend API URL
`AGENTRIX_WEBAPP_URL`	`https://agentrix.xmz.ai`	Web app URL (used for auth redirect)
`AGENTRIX_WORKSPACE_HOME_DIR`	`~/.agentrix/workspaces`	Task workspace root
`AGENTRIX_AGENTS_HOME_DIR`	`~/.agentrix/agents`	Custom agent install root
`AGENTRIX_CLAUDE_HOME`	`~/.claude`	Claude Code config dir
`AGENTRIX_CODEX_HOME`	`~/.codex`	Codex config dir
`AGENTRIX_PI_HOME`	`~/.pi/agent`	PI config dir; `PI_CODING_AGENT_DIR` is also supported
`AGENTRIX_GEMINI_HOME`	`~/.agentrix/config/gemini`	Gemini config dir
`AGENTRIX_API_KEY`	—	LLM gateway key read by `agentrix llm-config apply` and Docker auto-config
`AGENTRIX_API_KEY_FILE`	—	Read the LLM gateway key from a file
`AGENTRIX_BASE_URL`	`https://api.xmz.ai`	LLM gateway URL
`AGENTRIX_PI_MODEL`	Same as `AGENTRIX_CODEX_MODEL`	Default PI model
`AGENTRIX_CLAUDE_PATH`	—	Override the `claude` binary path
`AGENTRIX_CODEX_PATH`	—	Override the `codex` binary path
`AGENTRIX_LLM_AUTO_CONFIG`	`true`	Whether the Docker image auto-generates LLM config before daemon/start
`AGENTRIX_LLM_CONFIG_FORCE`	`false`	Whether Docker auto-config overwrites existing LLM config
`GITLAB_BASE_URL`	—	GitLab site URL for Docker/cloud runner auto-configuration
`GITLAB_API_URL`	`<base-url>/api/v4`	GitLab API URL used by auto-configuration
`GITLAB_TOKEN`	—	GitLab token saved to the local worker token store and, when user binding is enabled, synced as an API credential
`GITLAB_TOKEN_FILE`	—	Read the GitLab token from a file, useful with Docker secrets
`AGENTRIX_GITLAB_BIND_USER`	Local: `true`; Private Cloud: `false`	Whether auto-configuration binds the GitLab account to the current Agentrix user; an explicit value overrides the runtime default
`AGENTRIX_GITLAB_USE_AS_PROXY`	`true`	Whether auto-configuration registers the current runner as a Git proxy node
`AGENTRIX_GITLAB_AUTO_CONFIG`	`true`	Set to `false` to disable Docker/cloud runner GitLab auto-configuration
`AGENTRIX_DISABLE_CAFFEINATE`	—	Set to `true` to allow the machine to sleep during tasks
`CLOUD_AUTH_TOKEN`	—	Cloud runner auth token; set to the runner secret when deploying a Private Cloud runner
`CLOUD_AUTH_TOKEN_FILE`	—	Read the cloud runner auth token from a file
`DEBUG`	—	Enable verbose debug logging

Global Options​

agentrix start​

agentrix stop​

agentrix status​

agentrix doctor​

agentrix llm-config apply​

agentrix upgrade​

agentrix logout​

agentrix ls​

agentrix kill <sessionId>​

agentrix killall​

agentrix git-server add​

agentrix git-server list​

GitLab Webhook Setup​

Supported Events and Mapping​

Environment Variables​