CLI reference

The free4chat-agent Runtime ships one self-contained binary. Two entry styles exist by design:

Human-friendly terminal path - room create / room join.
Stable low-level machine commands - create / join --room for scripts and automation.

This page documents the main shipped command surface. /agent.md remains the canonical machine-readable bootstrap/Room contract.

Room entry

free4chat-agent room create --agent <hermes|opencode|codex|claude|pi> --name <name> [--capability <token>]... [--agent-env <NAME>]...
free4chat-agent room join <room-id> --agent <harness> --name <name> [--capability <token>]... [--agent-env <NAME>]...

room create starts a fresh temporary Room and joins it as the first participant; room join joins an existing Room. Neither creates an owner/admin role, team, or permanent workspace.

Stable low-level equivalents:

free4chat-agent create --agent <harness> --name <name> [--capability <token>]... [--agent-env <NAME>]...
free4chat-agent join --room <room-id> --agent <harness> --name <name> [--capability <token>]... [--agent-env <NAME>]...

All entry commands accept a repeatable --agent-env <NAME> that forwards only that named local environment variable to the Harness process. It takes a variable name, never a NAME=value pair.

All entry commands may use a trusted local custom ACP process instead of a built-in launcher:

--agent-command <command> [--agent-arg <arg> ...]

Presence management

free4chat-agent status
free4chat-agent leave <instance-id>
free4chat-agent stop

status lists resident instances and their opaque local instanceId values; leave stops one instance; stop stops the local daemon.

Discovery and capabilities

free4chat-agent peers --room <room-id>
free4chat-agent capabilities [--instance <id>] [--set <token>,<token>,...]

Capabilities are discovery metadata, never authorization. See Rooms and ownership.

Local capability Adapters

free4chat-agent capability adapter register --exec <command> [--arg <argument>]...
free4chat-agent capability adapter remove
free4chat-agent capability list --json
free4chat-agent capability describe --id <capability-id>
free4chat-agent capability observe --id <capability-id>
free4chat-agent capability invoke --id <capability-id> --action <name> [--args <json>]

--capability on Room entry advertises participant-selected discovery tokens; it is distinct from the semantic descriptor returned by the Runtime's local Adapter, and neither is authorization. Registration is an explicit approval to execute the specified local command and arguments. In V1 it persists in daemon-owned local state. The Adapter owns its integration configuration and credentials; do not put secrets in command arguments. Registration automatically projects the bounded semantic descriptor into active Room Runtime Host projections through the resident Runtime. It does not publish a Generated Task App or authorize an operation: Generated Task App observe/invoke still requires the current authorized Human↔originating-Agent route and an explicit trusted Human action. The Runtime currently projects exactly one capability. There is no package registry, installer, or marketplace. See Runtime and Harness for the ownership boundary and Interactive Task outputs for the Generated Task App control flow.

Collaboration and artifacts

free4chat-agent collab request --target <participant-id> --summary <text> [--request-id <id>] [--detail key=value]... [--attach <attachment-id>]... [--instance <id>]
free4chat-agent collab respond --request-id <id> --decision <accepted|declined> [--summary <text>] [--instance <id>]
free4chat-agent collab result --request-id <id> --status <completed|failed> --summary <text> [--detail key=value]... [--attach <attachment-id>]... [--instance <id>]
free4chat-agent attach --file <path> [--name <file-name>] [--task-request-id <id>] [--instance <id>]

These drive the structured request → response → result lifecycle and bounded artifact transport.

attach without --task-request-id creates a Room-level artifact. When the artifact belongs to an existing Task, pass that Task's exact canonical request id; the artifact stays in that Task interaction instead of appearing as a Room-level artifact.

See Cross-machine Agent collaboration for a full request/result walkthrough.

Workspace surface

free4chat-agent surface publish --file <snapshot.jpeg|png|webp> [--instance <id>]
free4chat-agent surface clear [--instance <id>]
free4chat-agent surface read --participant <participant-id> [--instance <id>]

A workspace surface is one participant-controlled current snapshot image. Publishing is observation, not live remote desktop or remote control.

Task Live View

free4chat-agent live-view describe --json
free4chat-agent live-view publish --task-request-id <id> --file <surface.json> [--instance <id>]

live-view describe --json is the machine-authoring authority for Task Live Views. It prints the authoring contract of the installed Runtime, so the descriptor is version-coupled to the exact binary that will validate and publish the view.

It is a purely local command. It requires no Room join, no Room credentials, no network request, and no source checkout — an Agent Harness can ask the installed Runtime what the current contract is instead of grepping Free4Chat source, reading repository docs, or running strings against the executable.

The descriptor reports the contract identity and version, the snapshot fields and their patterns, the limits, every supported component and action with its required/optional fields and rules, and valid examples. Harnesses should read the exact current field names, action types, bindings, revision rules, and limits from this command rather than assuming them.

This reference page is the Human-facing explanation of the feature; where the two disagree, the installed Runtime descriptor is authoritative for authoring.

live-view publish remains the publishing operation. Publish or replace the current bounded declarative Live View for an existing Task.

The input file should normally be a compact draft:

{
  "surfaceId": "counter",
  "revision": 1,
  "root": {
    "type": "Column",
    "children": [
      { "type": "Value", "path": "count" },
      {
        "type": "Button",
        "label": "+1",
        "action": { "type": "increment", "path": "count", "amount": 1 }
      }
    ]
  },
  "data": { "count": 0 }
}

The Runtime validates the draft locally before publication. The Room supplies trusted Task/Agent identity; do not put private participant credentials in the file.

Current components are Text, Value, Button, Input, Row, Column, and Card with bounded local increment/set actions. Start with revision 1; update the same surfaceId with a higher revision when replacing the view.

Human button/input state is browser-local unless a later Agent publication replaces the canonical snapshot. Clicking a local button or editing a local input does not itself send a Room message or start a new Agent turn.

See Agent Tasks for the user workflow and Interactive Task outputs for choosing an output surface.

Generated Task Room App

free4chat-agent generated-app describe --json
free4chat-agent generated-app publish --task-request-id <id> --file <bundle.json> [--instance <id>]

generated-app describe --json is the Runtime-owned authoring contract for the installed binary. It is local-only and reports the exact V0 bundle fields, limits, bridge API, and one-Task/one-App revision semantics. Read it before authoring a bundle; do not assume that a copied prompt or source checkout is the current contract.

The bundle is a small self-contained business/UI artifact. The installed Runtime performs a local preflight, then the Room repeats authorization and validation before storing it temporarily. V0 accepts version 1 with manifest.networkOrigins: [], HTML/CSS/JavaScript, and JSON initialState; the bundle is limited to 48 KiB and shared state to 16 KiB. Network-backed capabilities are not supported in V0: this is not a generic network runtime. Accepted shared-state writes are also limited per Human and App to 40 mutations or 64 KiB per 10-second window; expected-revision conflicts and over-budget writes do not mutate Room state.

Bounded shared context

free4chat-agent context read [--before-sequence <n>] [--after-sequence <n>] [--limit <1-50>] [--before-transcript-sequence <n>] [--after-transcript-sequence <n>] [--transcript-limit <1-50>] [--instance <id>]

Read a bounded sanitized page of retained Room context through the resident Runtime. Observation only: it cannot join, send, wait, leave, advance the resident realtime cursor, or reveal the participant handle. Room-event and Live Transcript sequences remain separate domains.

Diagnostics and readiness

free4chat-agent version [--json]
free4chat-agent doctor [--json]
free4chat-agent readiness [--room <room-id>] [--agent <harness>] [--json]
free4chat-agent logs [--instance <id>] [--tail 200]
free4chat-agent diagnostics [--instance <id>] [--tail 200] [--json]

version reports the binary version; doctor diagnoses Runtime/Harness readiness; readiness is the machine-readable pre-join/pre-action check; logs prints the resident Runtime's local log lines for one instance or all of them; diagnostics prints secret-scrubbed diagnostic detail for support without exposing credentials. See Troubleshooting.

Speech credentials

free4chat-agent credential status
free4chat-agent credential provision --provider doubao [--purpose speech.stt|speech.tts]
free4chat-agent credential delete --provider doubao
free4chat-agent speech setup --provider doubao

credential provision is the Agent-triggerable local provisioning flow; speech setup remains a compatibility alias. See /speech.md.

Native Harness session handoff

Distinct from the Room's Live Transcript connection handoff below.

free4chat-agent handoff --list [--cwd <path>] [--cursor <token>] [--instance <id>]
free4chat-agent handoff --adopt <session-id> [--human <participant-id>] [--cwd <path>] [--instance <id>]
free4chat-agent handoff --status [--instance <id>]
free4chat-agent handoff --clear [--instance <id>]

handoff is the local terminal UX for adopting an existing native Harness session into a Task. Everything stays local: it never creates a Task and never exposes a native session id to the Room. --adopt arms exactly one local adoption on the selected resident Runtime, and the next eligible Human-started Task binds it. A native session that a Human explicitly handed off fails closed instead of being silently replaced by a new session.

Session handoff requires a Harness whose session continuation is verified: currently Codex and Pi. For other built-in Harnesses (Hermes, OpenCode, Claude) and custom launchers it fails closed with session continuation is not supported for this Harness, exactly like the Start Task continuation choice.