Build
CLI reference
One binary drives the whole loop, from logging in and connecting a system to deploying an operator and exporting the receipts it produced. The CLI shares its version line with the SDKs, so fibric --version should match the SDK in your project. Every command takes --help and --json.
Install #
Install once, globally. The CLI ships standalone, so it does not need a project to exist yet, you can fibric login from an empty directory and scaffold from there.
# Homebrew
brew install fibric/tap/fibric
# or the install script
curl -fsSL https://get.fibric.io | sh
# or via npm (Node 18+)
npm install -g @fibric/cli
# confirm
fibric --version # fibric 1.4.0Authenticate #
fibric login opens a browser, links your workspace, and writes a short-lived token to ~/.fibric/credentials. For CI and servers, mint a non-interactive token and pass it as FIBRIC_TOKEN. A token resolves to exactly one workspace and tenant, it can never read or act across the wall.
# interactive, for your machine
fibric login
fibric workspace use paperco-prod
fibric whoami # confirms the active workspace + tenant
# non-interactive, for CI / servers
export FIBRIC_TOKEN="fbc_live_..." # mint with: fibric token create --name ci
fibric whoami --json| Command | What it does |
|---|---|
fibric login | Authenticate in the browser and link a workspace. |
fibric logout | Clear the local credentials at ~/.fibric/credentials. |
fibric whoami | Show the active workspace, tenant, and token expiry. |
fibric workspace list | List workspaces your account can reach. |
fibric workspace use <name> | Select the active workspace and tenant. |
fibric token create --name <n> | Mint a non-interactive, tenant-scoped token for CI. |
fibric token revoke <id> | Revoke a token immediately. |
A FIBRIC_TOKEN resolves to one tenant and only that tenant. Treat it like any production secret, keep it out of source, rotate it with fibric token revoke and a fresh token create. Isolation is enforced by the platform, not by the token holder.
connector #
Scaffold, validate, test, and publish connectors. A connector teaches Fibric to sense and act on one system; publishing lists it for any tenant to install. See the Connector SDK for the code side.
| Command | What it does |
|---|---|
fibric connector scaffold <name> | Generate a new connector project from a template (TS or Py). |
fibric connector validate <dir> | Check a connector against the marketplace contract. |
fibric connector test <name> <tool> | Run one tool against a real connection. Reads run; side-effecting tools dry-run. |
fibric connector publish <dir> | Publish a versioned, immutable connector to the marketplace. |
fibric connector list | List connectors installed in the active tenant. |
fibric connector show <name> | Show a connector's capabilities, versions, and auth shape. |
fibric connector deprecate <name>@<ver> | Mark a version line deprecated without unpublishing it. |
fibric connection create | Hold credentials for one account of a connector. |
# scaffold, validate, publish a warehouse connector
fibric connector scaffold acme-wms --lang ts
fibric connector validate ./acme-wms
fibric connector publish ./acme-wms --version 1.2.0
# create a connection holding one account's credentials
fibric connection create acme-wms --name acme-eastoperator #
Operators sense, reason, and propose a validated ExecutionPlan. They never act directly. operator run --dry-run shows you the plan an operator would submit, every step, capability, and idempotency key, without disposing of any of it.
| Command | What it does |
|---|---|
fibric operator list | List operators deployed in the active tenant. |
fibric operator deploy <file> | Deploy an operator from its manifest. |
fibric operator run <name> --dry-run | Show the ExecutionPlan it would propose, without acting. |
fibric operator run <name> | Run the operator for real. Side-effecting steps go through the executor. |
fibric operator logs <name> | Stream sense and reason traces for a run. |
fibric operator disable <name> | Stop an operator from being scheduled or triggered. |
# deploy, then preview the plan before letting it act
fibric operator deploy ./operators/order-risk-watcher.ts
fibric operator run order-risk-watcher --dry-run
# example dry-run output:
# PLAN order-risk-watcher 2 steps
# 1 order.hold { orderId: SO-44817 } key=hold:SO-44817:2026-06-13
# 2 order.hold { orderId: SO-44902 } key=hold:SO-44902:2026-06-13
# nothing has acted. run without --dry-run to submit.plan #
A plan is a proposal, a set of side-effecting steps an operator wants the executor to dispose of. You can inspect a pending plan, submit a hand-written one, or cancel one before it runs. The model proposes; the executor disposes.
| Command | What it does |
|---|---|
fibric plan list | List recent plans and their state (proposed, vetoed, disposed). |
fibric plan show <id> | Show a plan's steps, the policy rule applied, and idempotency keys. |
fibric plan submit <file> | Submit a hand-authored plan to the executor. |
fibric plan cancel <id> | Cancel a proposed plan before any step is disposed. |
policy #
Your trust policy is what the executor checks every side-effecting step against. It is fail-closed: if no rule allows a step, the step does not run. Policy is versioned config, apply it, diff it, roll it back.
| Command | What it does |
|---|---|
fibric policy apply <file> | Apply a trust policy for the active tenant. |
fibric policy show | Print the policy currently in force. |
fibric policy test <plan-id> | Replay a plan against the policy to see what would pass or be vetoed. |
receipt #
Every disposed step writes a receipt: the proposal, the policy rule that allowed it, the idempotency key, and the result. Receipts are the audit trail, immutable, exportable, and scoped to your tenant. Nothing acts without leaving one.
| Command | What it does |
|---|---|
fibric receipt list | List actions taken, with their reasons and results. |
fibric receipt show <id> | Show one receipt in full, including the policy rule and the raw result. |
fibric receipt export | Export the receipt ledger for compliance (CSV or JSONL). |
# what did order-risk-watcher actually do this week?
fibric receipt list --operator order-risk-watcher --since 7d
# export the full ledger for an auditor
fibric receipt export --since 2026-01-01 --format jsonl > receipts-2026.jsonldeploy #
fibric deploy reads a fibric.toml in the current directory and applies everything in it as one unit: connectors to publish, operators to deploy, and the policy to enforce. It is the one command CI runs. Pass --dry-run to print the plan of changes without applying any.
# preview everything this commit would change
fibric deploy --dry-run
# apply for real (this is what CI runs after tests pass)
fibric deploy
# fibric.toml, the unit of deploy
# [workspace]
# name = "paperco-prod"
# [[connectors]]
# path = "./connectors/acme-wms"
# [[operators]]
# path = "./operators/order-risk-watcher.ts"
# [policy]
# path = "./policy/trust.yaml"Exit codes #
Every command returns a stable exit code so you can branch on it in CI. A vetoed plan is its own code, distinct from a crash, because a policy veto is a correct, fail-closed outcome, not an error in your pipeline.
| Code | Meaning |
|---|---|
| 0 | Success. The command did what it said. |
| 1 | Generic failure. Something went wrong; the message says what. |
| 2 | Usage error. A flag or argument was missing or malformed. |
| 3 | Authentication error. No valid token, or the token is expired or revoked. |
| 4 | Policy veto. A side-effecting step was correctly fail-closed by your trust policy. |
| 5 | Validation error. A connector or plan failed the marketplace or schema contract. |
| 7 | Conflict. Single-flight could not acquire the entity; another action holds it. |
Every command takes --help, and fibric <group> --help lists its subcommands. Add --json to any read command for machine-readable output, and exit code 4 lets CI treat a policy veto as a stop, not a crash.
To build the connectors and operators these commands ship, see the Connector SDK and SDKs & CLI. For what runs on the other side of plan submit, see Governance & trust.