Command reference: agents, runs, and specs

Overview

These commands manage agents and their runs. They need a browser sign-in, an API address, and a server that supports agents; otherwise they stop with “This server does not support the requested CLI feature: agents” (exit code 6). Commands that list or create items in a workspace take --org <workspace-id> or use the profile’s orgId.

Console

figena console bootstrap

Binds the workspace to the agent console. Requires --org or the profile’s orgId.

figena console status

Shows the server version and the capabilities it reports to the CLI.

Agents

figena agents list

Lists the agents in a workspace. Option: --org <workspace-id>.

figena agents get <agentId>

Shows one agent.

figena agents create

Creates an agent. Options: --name <name> (required), --description <text>, and --org <workspace-id>.

figena agents version create <agentId>

Creates a version from a workflow spec. Pass the spec as a file with --spec <file> or inline with --spec-json '<json>'. Add --allow-unknown to accept fields the server doesn’t recognize.

figena agents version get <versionId>

Shows one agent version.

figena agents publish <versionId>

Publishes a version so it can be run.

figena agents deploy <agentId>

Creates a version from a spec and, depending on the options, publishes it, runs a smoke test, and promotes it, all in one request. Name the agent with <agentId> or --agent <agentId>, and pass the spec with --spec or --spec-json (required).

• --publish: publish the new version.
• --promote-default: make the new version the agent’s default.
• --run-smoke: run a smoke test. Supplying --smoke-input <file> or --smoke-input-json '<json>' turns the smoke test on automatically.
• --wait: wait for the deployment to finish, up to --timeout (default 10m).
• --allow-unknown: accept spec fields the server doesn’t recognize.
• --rollback-on-fail: the CLI accepts this option and sends it with the request, but the current server doesn’t act on it. A failed deploy is not rolled back automatically, so check the result before promoting a version.

figena agents deploy <agentId> \  --spec ./workflow.json \  --publish --promote-default \  --smoke-input ./smoke-input.json \  --wait --timeout 5m

When the request succeeds, the CLI prints “Agent deploy completed” with the server’s result.

Runs

figena run <versionId>

Runs a published version. Pass inputs with --input <file> or --input-json '<json>'; --trigger-type defaults to manual. By default the CLI waits until the run is succeeded, failed, needs_approval, or canceled, up to --timeout (default 10m). Add --detach to return as soon as the run starts.

figena runs list

Lists runs in a workspace. Options: --org, --agent <agentId>, --status <status>, and --page-size <n> (or --limit <n>).

figena runs get <runId>

Shows one run.

figena runs steps <runId>

Lists the steps of a run.

figena runs trace <runId>

Shows the run’s trace summary. To trace a published invocation instead, pass --session-id <id> and optionally --run-id <id>.

figena runs wait <runId>

Waits until the run reaches a final state: succeeded, failed, needs_approval, or canceled. The CLI checks after 1, 2, and then every 4 seconds. If the run hasn’t finished within --timeout (default 10m), the command stops with exit code 7.

Workflow specs

figena spec validate <file>

Sends a JSON spec file to the server for validation and prints “Workflow spec is valid” or “Workflow spec is invalid” with the details. Add --allow-unknown to accept fields the server doesn’t recognize. An invalid spec returns ok: false with exit code 0, so scripts should check ok.

figena spec inspect <file>

Validates the spec while accepting unknown fields and returns the validation result together with the spec’s metadata section.

A typical release

figena spec validate ./workflow.jsonfigena agents version create <agentId> --spec ./workflow.jsonfigena agents publish <versionId>figena run <versionId> --input-json '{"question":"What changed this week?"}'