CLI reference

The ficus command connects your terminal to a Ficus instance. Use it to inspect squads, create and follow work streams, and script supported actions. The examples below assume ficus is installed and available on your PATH; check with ficus --version.

Log in to an instance

Choose a short label for the connection, such as work. Ficus calls a saved connection a backend.

Ficus Cloud

Use the URL of your own Ficus workspace. Replace the fictional https://ficus.example.com address before running:

ficus auth login work --api-url https://ficus.example.com

Self-hosted

Use your instance’s browser-facing base URL. If you are running the CLI on the same machine as a local instance on port 3000:

ficus auth login local --api-url http://localhost:3000

For a remote server, replace the URL with that server’s address. See Runtime and access if the instance is not reachable.

Without an explicitly supplied credential, login opens browser approval or prints a URL to open. Sign in to the intended account and approve the CLI. The command saves the paired credential and makes this backend active.

Check the target and identity before creating work:

ficus auth status
ficus whoami
ficus auth introspect

auth status explains how the CLI found its credentials. whoami identifies the instance and caller; auth introspect shows effective roles and permissions. Explicit environment credentials can affect authentication, so check these when the CLI appears to use the wrong account.

Find a squad and workflow

ficus squad list
ficus workflow list
ficus agent-type list

Copy an actual squad ID from the list. This example value is fictional and must be replaced:

SQUAD_ID='00000000-0000-4000-8000-000000000001'
ficus squad get "$SQUAD_ID"
ficus workstream list --squad "$SQUAD_ID"

If you need a squad, this creates one with a name and purpose:

ficus squad create "Website refresh" --purpose "Improve the public website"

Read Squads to choose its workspace and configuration before assigning work.

Create and inspect a work stream

Choose a workflow from ficus workflow list. This example uses the bundled solo style, which gives one participant the deliverable:

ficus workstream create "Draft release notes" \
  --squad "$SQUAD_ID" \
  --workflow solo \
  --description "Draft release notes from the changes provided in the squad. Identify anything that needs verification."

Participants are created when their flow steps are reached. You do not need to pre-spawn agents for this style-based path. See Workflows for choosing a flow and completion behavior.

Copy the returned work-stream ID. Replace this fictional value before running:

WORKSTREAM_ID='00000000-0000-4000-8000-000000000002'
ficus workstream get "$WORKSTREAM_ID"
ficus workstream get "$WORKSTREAM_ID" --metrics
ficus workstream list --squad "$SQUAD_ID" --no-truncate

ws is an alias for workstream; at is an alias for agent-type. To find work by text:

ficus search "release notes" --squad "$SQUAD_ID" --limit 10

Use multiple instances

List saved backends, switch the default, or select one for a single command:

ficus auth list
ficus auth switch work
ficus --backend work squad list

Replace work with a label you have saved. Backend selection is for a person’s CLI session. Ficus-built agent shells use their injected agent identity and reject --backend so they do not accidentally pick up an operator login.

Use JSON in scripts

Add --json for machine-readable output:

ficus --json squad list
ficus --json workstream get "$WORKSTREAM_ID"
ficus --json auth introspect --squad "$SQUAD_ID"

Inspect the command’s returned fields before writing a script around them. A successfully retrieved work-stream record is not evidence that its work is complete; check its status and any outstanding input or review request.

For automation, use a separately scoped system token. Supply FICUS_API_URL and FICUS_TOKEN through your automation’s secret/environment configuration rather than placing a token in a command or checked-in script.

Discover commands and troubleshoot

Inspect disk usage

Read the same cached breakdown shown in Settings → Storage, or request a background scan:

ficus system storage --json
ficus system storage --refresh --json

Both commands return immediately with scanning, scannedAt, error, and the per-machine, squad, and folder sizes in bytes. While scanning is true, read again after a few seconds; existing results retain the previous scan’s timestamp until the scan finishes. Check each machine’s status: unavailable or partial measurements are not evidence of an empty disk. Folder totals include their children.

Each squad’s top-level folders carry a kind: squad-workspace, or agent with an agent object (id, label, agentTypeId, status, lastMessageAt, dormantAt, createdAt). The agent fields are read from the database each time, so a status change shows before the next scan. dormantRetentionDays is how long dormant agents are kept before automatic removal. Results saved before an upgrade can lack these fields until the next scan.

Squads and folders also have a status. On an interrupted scan, completed child measurements are retained under partial parents without counting overlapping subtrees twice. A bytes: null value means nothing was measured, rather than zero usage. Folder path identifies the measured directory. Machine diagnostics includes the command’s exitCode, reason codes such as scan_timeout or permission_denied, and expectedHomes, measuredHomes, and missingHomes. Missing home totals alone do not establish whether a directory is absent, unreadable, or simply not reached before the time limit.

Storage scans also run on the worker every 12 hours by default. Configure the interval and capacity alerts in Settings → Storage. Reading storage does not itself trigger a scan; a manual refresh queues one for the next worker check. --refresh has a one-minute cooldown; concurrent requests share the running scan. This requires system:logs permission and VM sandbox machines. Other runtimes return supported: false. The User Assistant can use these commands with your permissions.

The API equivalents are GET /api/system/storage and POST /api/system/storage/refresh, with the same permissions and persisted results. GET /api/system/storage/files (also system:logs) returns per-squad totals of attachments and images stored by Ficus, compared with the attachment quota, on every runtime. Cleanup actions in Settings → Storage use DELETE /api/squads/:id/agents/:agentId (make dormant), GET /api/squads/:id/idle-consultants?days=N and POST /api/squads/:id/idle-consultants/dormant (agents:terminate), and POST /api/system/storage/dormant-agents/remove (system:cleanup; returns 202 and removes the accepted agents in the background). See disk troubleshooting for measurement limits.

Get help

ficus --help
ficus workstream create --help
ficus agent-type update --help
ficus integration --help
ficus provider-auth --help

Symptom	What to check
Wrong instance or account	Run `ficus auth status` and `ficus whoami`; inspect explicit environment overrides and the active backend.
Unauthorized	Log in again or check whether the paired device was revoked.
Forbidden	Run `ficus auth introspect --squad "$SQUAD_ID"` and ask an administrator for the required access.
No usable model	Check provider accounts and the selected model tier.
Unknown option	Read that command’s `--help`; CLI and server versions may differ.

To disconnect a saved backend:

ficus auth logout work

Normal logout revokes its paired device and removes the local credential. If the server is unreachable, ficus auth logout work --local-only removes the local entry without revoking the remote device; revoke it later in Settings → Paired Devices.

For a guided first run, follow Your first task.

Work references

Use the short number shown in Ficus for work-stream commands:

ficus workstream get 42
ficus workstream get '#42'

Full UUIDs and unique UUID prefixes remain accepted. --json responses retain the UUID id and include number; --id-only prints the public number. In API paths, use /api/workstreams/42 or encode the hash: /api/workstreams/%2342.