Forge Agent CLI reference

Curated syntax for signed Windows/Linux CLI 0.17.5. See releases. Platform and product versions are independent. Customer-intake additions below are explicitly source-only until a separately approved signed CLI publication and compatible Bridge deployment.

Conventions and output

forge --version
forge help
forge capabilities
forge guide
forge doctor

--version prints the installed version. capabilities describes commands and platform selections; doctor checks local readiness and login, not the health of every remote device.

For commands below, angle-bracket text is a placeholder to replace. Square brackets mean optional syntax; | means choose one value. Do not type those notation characters literally. UUIDs identify records; file paths identify local inputs/outputs unless explicitly called remote paths. Neither is a substitute for authorization.

Common options:

Option	Meaning
`--tenant <profile>`	Select one isolated local named profile without changing the default.
`--format json`	Stable machine-readable envelope. Use explicitly in automation.
`--format text`	Human-readable output.

Interactive login, whoami and devices list can use readable terminal output. Redirected/JSON commands preserve non-prompting workspace selection. Browser authentication remains explicit.

Normal command envelopes contain:

Field	Contract
`schema_version`	`"1.0"` for the CLI envelope, independent of a nested diagnostic schema.
`command`	Operation name.
`ok`, `status`	Success flag and operation-specific state.
`data`	Typed command result, or null.
`errors`	Entries with `code`, `message` and optional `remediation`.
`next_actions`	Entries with `description` and suggested `command`.
`timestamp_utc`	Result timestamp.

Envelope commands exit 0 when ok is true and 1 when false. Inspect the data as well: a partially created batch may contain successful and failed items. For exec, the actual remote exit code is data.exit_code; it is not the CLI process's exit code.

Identity and profiles

forge login [--workspace <workspace-id>] [--non-interactive]
forge whoami
forge logout [--all]
forge tenant list
forge tenant show
forge tenant use <profile>
forge devices list [--all-tenants]
forge devices show --device <device-id>

Use forge login --tenant <profile> --workspace <workspace-id> for an isolated membership profile. --non-interactive prevents the workspace prompt; it does not perform browser consent or MFA for you. Routine login discovers public configuration from Forge; no custom Bridge or identity-provider flags are needed.

Linux requires forge credentials configure and forge credentials status before login. See Linux installation for the provider-specific command syntax.

Access and transfers

forge device connect --device <device-id>
forge device disconnect --device <device-id>
forge exec --device <device-id> --command "<target-shell-command>" [--timeout-seconds <seconds>]
forge upload --device <device-id> --source <local-file> --destination <remote-file>
forge download --device <device-id> --source <remote-file> --destination <local-file>
forge device transfer accept [--expires-in-minutes <minutes>]
forge device transfer initiate --device <device-id> --acceptance-code <private-one-use-code>
forge device transfer cancel --transfer <transfer-id>

Transfer acceptance defaults to 30 minutes and is created in the destination workspace. Initiation runs in the source workspace. These move device ownership; they are not file-transfer commands.

See access for elevated execution, exclusive leases, profile selection, host-key protection and interrupted-operation behavior. device relay probe is a migration-specific command, not an ordinary health check. Retired transport commands are not a supported fallback.

Enrollment

forge enrollment create --display-name "<label>" --out <directory> [--platform win-x64|linux-x64]
forge enrollment batch create --manifest <csv-file> --out <directory> [--platform win-x64|linux-x64] [--concurrency <count>]
forge enrollment batch status --batch <batch-id> [--wait] [--timeout-seconds <seconds>]
forge enrollment share create --display-name "<label>" --platform win-x64|linux-x64 --out <new-directory> [--expires-in-minutes <minutes>]
forge enrollment share status --share <share-id>
forge enrollment share revoke --share <share-id>

Single and batch creation accept --expires-at <ISO-8601-timestamp> or --expires-in-minutes <minutes>. Single creation also accepts --primary-user "<label>" and --organization "<label>". Batch concurrency defaults to four, and waiting for batch status defaults to 600 seconds.

A batch CSV requires the headers display_name, primary_user and organization; the latter two may have empty values. Optional folder and platform columns choose an output subfolder and target platform per row:

display_name,primary_user,organization,folder,platform
Example Windows device,,,windows-device,win-x64
Example Linux device,,,linux-device,linux-x64

Use private output folders. Generated Windows filenames, Linux code files and enrollment links contain enrollment capabilities. A share ID and batch ID are non-secret selectors, not those capabilities. See enrollment.

Diagnostics

forge diagnostics collect --device <device-id> --sections <comma-separated-sections> --output <local-json-file>
forge diagnostics collect --rescue-code <session-code> --profile <profile> --output <local-json-file>

Choose exactly one target and one selection form. Available platform sections/profiles, optional Windows SMART inputs and result interpretation are authoritative in the diagnostics guide.

Customer directory

In the following syntax, choose companies or contacts:

forge companies|contacts list [--search "<name>"] [--archive active|archived|all] [--limit <1-100>] [--cursor <cursor>]
forge companies|contacts search --search "<name>" [--archive active|archived|all] [--limit <1-100>]
forge companies|contacts show --id <id>
forge companies|contacts create --input <json-file|->
forge companies|contacts update --id <id> --input <json-file|->
forge companies|contacts archive|restore --id <id> --version <current-version>
forge device customer-links show --device <device-id>
forge device customer-links update --device <device-id> --input <json-file|->

Contact lists/searches additionally accept --company <company-id>. Source intake accepts a supplied durable idempotency_key in create JSON, not in updates. Keyed creates check a fresh authenticated X-Forge-Intake-Version: 1 response before writing. forge capabilities describes client syntax, not proof that the selected Bridge supports it. Read customers for complete JSON examples, full replacement semantics and archive handling.

Cases, notes and drafts

forge cases list [--archive active|archived|all] [--device <device-id>] [--session <session-id>] [--cursor <cursor>] [--limit <1-50>]
forge cases show --case <case-id>
forge cases create --input <json-file|->
forge cases update --case <case-id> --input <json-file|->
forge cases status --case <case-id> --version <version> --status open|in_progress|waiting
forge cases close|reopen|archive|restore --case <case-id> --version <version>
forge cases collaborators --case <case-id>
forge cases assign|unassign --case <case-id> --member <member-id> --version <version>
forge cases links --case <case-id>
forge cases link --case <case-id> --kind device|session --target <target-id> --version <version>
forge cases unlink --case <case-id> --link <link-id> --version <version>
forge cases notes list --case <case-id> [--cursor <cursor>] [--limit <1-50>]
forge cases notes show --case <case-id> --note <note-id>
forge cases notes revisions --case <case-id> --note <note-id> [--cursor <cursor>] [--limit <1-50>]
forge cases notes create --case <case-id> --input <json-file|->
forge cases notes update --case <case-id> --note <note-id> --input <json-file|->
forge cases drafts list --case <case-id> [--cursor <cursor>] [--limit <1-50>]
forge cases drafts show --case <case-id> --draft <draft-id>
forge cases drafts create --case <case-id> --input <json-file|->
forge cases drafts update --case <case-id> --draft <draft-id> --input <json-file|->

Source intake extends cases list with --search <text>, --status open|in_progress|waiting|closed, --company <id> and --contact <id>. These filters require the version-1 intake marker on the authenticated response; unsupported servers cannot silently return unfiltered results. Case/draft creates also accept optional persisted idempotency_key in their existing V1 JSON. No automatic mutation retry occurs.

Use at most one exact device/session filter for case backlinks. Note creation requires a stable idempotency_key. Draft edits clear review; there is no CLI review or send command. JSON shapes and lifecycle rules are in cases.

intake_outcome_unknown reports an unconfirmed mutation, not safe failure. Preserve the original request and reconcile current records in the same profile. Never replace the key to retry an uncertain create; server rollback needs operator reconciliation. See customer intake for search-before-create semantics, preservation-first triage and the pending access-link integration boundary.

Rescue

forge rescue guide
forge rescue capabilities
forge rescue doctor
forge rescue session create --label "<target-label>" [--platform win-x64|linux-x64] [--out <directory>]
forge rescue session list
forge rescue session status --code <session-code>
forge rescue session connect --code <session-code>
forge rescue session enroll --code <session-code> [--label "<device-label>"]
forge rescue session close --code <session-code>

Use Rescue only with matching signed-payload prerequisites and explicit customer authority. History IDs are not session codes. Promotion requests persistent access; closing requests temporary cleanup.

Mistake History

forge mistakes record --agent "<agent-name>" --note "<bounded-factual-note>" [--device <device-id>] [--customer "<plain-label>"] [--occurred-at <ISO-8601-timestamp>]
forge mistakes list [--since <ISO-8601-timestamp>] [--device <device-id>]

Use this separate append-only record for a material unintended change made by an agent, not routine case progress, rejected operations or harmless command typos. It is retained indefinitely. Keep the note factual and exclude secrets, transcripts and unnecessary customer content.

Installation maintenance

forge update installs the latest verified technician release. Platform setup, repair and uninstall differ; follow the Windows or Linux guide.

Machine configuration, acceptance-run administration and platform migration operations are not ordinary customer workflows. Their presence in discovery output does not grant authority to use them.

Table of Contents