CLI reference

The fibric CLI is the working surface for building and operating on the platform: authenticate, scaffold, run the local kernel, manage connectors and operators, follow receipts, and publish. Every read command takes --json for machine output, every command returns a stable exit code, and a policy veto exits distinctly from a crash, because fail-closed is a correct outcome, not an error.

#Install

npm install -g @fibric/cli     # Node 18+

$ fibric --version
fibric 1.0.2

#auth

Authentication is tenant-scoped by construction. A credential resolves to exactly one workspace and tenant; there is no flag that widens it.

#fibric auth login

Opens a browser, completes the device flow, and writes a short-lived token to ~/.fibric/credentials. For CI, skip the browser entirely and set FIBRIC_TOKEN in the environment.

$ fibric auth login
  opening https://app.fibric.io/device ... done
  confirm code: KHWM-PLXC
  linked workspace paperco-prod (tenant t_8f2a)
  credentials written to ~/.fibric/credentials (expires in 12h)

#fibric auth logout

Deletes the local credentials file and revokes the session server-side. Tokens minted for CI are unaffected; revoke those individually from the workspace settings.

$ fibric auth logout
  session revoked. ~/.fibric/credentials removed.

#fibric auth whoami

Prints the active identity: workspace, tenant, reseller if any, and token expiry. The first thing to run when anything behaves unexpectedly, because most surprises are "wrong workspace".

$ fibric auth whoami
  workspace  paperco-prod
  tenant     t_8f2a
  reseller   (none — Fibric direct)
  token      expires 2026-07-03T08:02Z

$ fibric auth whoami --json
{"workspace":"paperco-prod","tenant_id":"t_8f2a","reseller_id":null,"expires":"2026-07-03T08:02:00Z"}

#fibric init

Scaffolds a project: source layout, a fixtures directory, a starter trust policy, TypeScript config, and a CI workflow matching the CI recipe. Works in an empty directory before you have authenticated.

$ fibric init brightdesk --template connector --name cn-brightdesk
  created brightdesk/
    src/index.ts            defineConnector() starter, 1 read + 1 governed write
    fixtures/sample.jsonl   one replayable envelope
    policy/trust.yaml       default-closed starter policy
    tests/plan.test.ts      plan + policy assertions
    .github/workflows/connector-ci.yml
  next: cd brightdesk && npm install && fibric dev

#fibric dev

Runs the local kernel against the current project: in-process bus, in-memory executor, file-backed secret stub, watch mode. Side-effecting handlers are stubbed unless a sandbox connection is explicitly attached. The testing page covers the harness in depth, including fibric dev replay.

$ fibric dev
  fibric dev 0.9  ·  local kernel  ·  tenant t_local
  loaded connector cn-brightdesk@1.0.0 (2 tools, 1 event)
  executor: in-memory, policy from ./policy/trust.yaml
  watching src/ fixtures/  ·  webhooks on :4310

  [10:14:03] envelope  conversation.created  src=fixture
  [10:14:03] dispose   note.write            ALLOW (handler stubbed)

#connectors

#fibric connectors list

Lists connectors installed in the active tenant, with connection health from each connector's probe.

$ fibric connectors list
  ID                 VERSION  CATEGORY  CONNECTIONS  PROBE
  cn-kustomer        2.1.0    comms     1            ok (open conversations: 214)
  cn-magento         1.8.2    commerce  1            ok (open orders: 1,182)
  cn-amazon-connect  1.3.0    voice     1            ok

#fibric connectors add

Installs a connector into the tenant, from the marketplace by id or from a local directory during development, and walks the handshake the def's auth declares: an API key prompt for api_key, the authorization flow for oauth2. The secret goes directly into the tenant's secret store; the CLI never writes it to disk.

$ fibric connectors add cn-brightdesk --connection brightdesk-sandbox \
    --config '{"subdomain":"acme-sandbox"}'
  cn-brightdesk@1.0.0 requires: api key
  paste key (input hidden): ********
  key stored in tenant secret store. running probe... ok
  connection brightdesk-sandbox is healthy. 2 tools, 1 event stream live.

#fibric connectors test

Exercises one tool against a named connection. Reads execute. Side-effecting tools dry-run by default: input validation and the trust evaluation run, the handler does not. --contract validates the whole def against the marketplace contract instead, which is the form CI uses.

$ fibric connectors test cn-brightdesk note.write \
    --connection brightdesk-sandbox \
    --args '{"conversation_id":"cnv_3021","body":"test note"}'
  note.write is side-effecting: dry run (pass --live to execute)
  input validation   ok
  trust evaluation   ALLOW (rule: tool=note.write)
  handler            not called (dry run)

#operators

#fibric operators list

Lists operators in the tenant with their mode, trigger, and the pack version each was installed from.

$ fibric operators list
  NAME        PACK                     MODE          TRIGGER        LAST RUN
  order-risk  op-order-sentinel@2.3.1  live          every 15m      3m ago (2 actions)
  analyst     op-radar-analyst@1.6.0   live          on ask         41m ago
  floor       (local)                  propose-only  pick.*         12m ago (plan queued)

#fibric operators create

Creates an operator, either from a marketplace pack with --from, which walks capability binding and guardrail acceptance as shown on the operator packs page, or from a local definition file. New operators start in propose-only mode unless you say otherwise.

#fibric operators pause

Stops an operator from being triggered or scheduled. In-flight actions complete under their single-flight locks; nothing new is proposed. Pausing never loses state, and resume picks up the schedule where it left off.

$ fibric operators pause order-risk
  order-risk paused. 1 in-flight action will complete; no new runs will start.
  resume with: fibric operators resume order-risk

#receipts

Every disposed action leaves a receipt: the proposal, the decision (ALLOW, BLOCK, ALERT, or DEDUP), the idempotency key, and the outcome. The CLI reads the same ledger the audit trail and billing meter read.

#fibric receipts tail

Follows receipts live, like tail -f on what your operators are doing right now. Blocked actions appear in the stream too; fail-closed refusals are events worth watching.

$ fibric receipts tail --operator order-risk
  14:20:11  order.hold    ALLOW  ok    key=order-risk:SO-11290:hold
  14:20:11  notify.send   ALLOW  ok    key=order-risk:SO-11290:notify
  14:35:12  order.hold    DEDUP  ok    key=order-risk:SO-11290:hold
  14:50:14  order.refund  BLOCK  --    blocked by trust policy (maxValue)

#fibric receipts export

Exports the ledger for audit or analysis. With --envelopes it emits the triggering envelopes as replayable JSONL, which is how test fixtures are recorded.

$ fibric receipts export --since 2026-06-01 --format jsonl > receipts-june.jsonl
  8,412 receipts exported.

$ fibric receipts export --envelopes --since 7d > fixtures/last-week.jsonl
  1,204 envelopes exported (replayable; tenant rewritten to t_local).

#fibric publish

Validates a connector or operator pack together with its listing metadata and submits the proposal for review. During early access, the Fibric team reviews every proposal; nothing is visible to other tenants until it is approved. Field requirements and the review process are on the publishing page.

$ fibric publish ./brightdesk
  validating def cn-brightdesk@1.0.0        ok
  validating listing.json                    ok
  contract tests (2 tools, 1 event)          ok
  submitted proposal pub_01j9x2 for review (status: proposed)

$ fibric publish --status pub_01j9x2
  pub_01j9x2  cn-brightdesk@1.0.0  proposed  in review since 2026-07-01

#Exit codes

Stable across versions, so CI can branch on them. Code 4 is deliberate: a trust-policy veto is fail-closed working as designed, and a pipeline should treat it as a stop, not a crash.

Every command accepts --help, and fibric <group> --help lists its subcommands. For the programmatic equivalents of these commands, see the SDKs page and the API overview.