SDKs & CLI

# the CLI (Node 18+)
npm install -g @fibric/cli

# the SDK, in your project
npm install @fibric/sdk

# the CLI ships standalone; the SDK is on PyPI (Python 3.10+)
pipx install fibric-cli
pip install fibric

# interactive, for your machine
fibric login
fibric workspace use paperco-prod

# non-interactive, for CI / servers
export FIBRIC_TOKEN="fbc_live_..."     # mint with: fibric token create --name ci
fibric whoami                          # confirms the token resolves to a workspace

import { defineConnector, tool, auth } from "@fibric/sdk";
import { z } from "zod";

export default defineConnector({
  name: "acme-wms",
  summary: "Acme warehouse management system",

  // credentials are resolved from the vault, never hard-coded
  auth: auth.apiKey({ header: "X-Acme-Key", secret: "ACME_API_KEY" }),

  tools: [
    // read-only: senses the world, no side effects
    tool({
      name: "list_open_orders",
      capability: "order.read",
      input: z.object({ since: z.string().datetime() }),
      async run({ input, ctx }) {
        return ctx.http.get(`/orders?status=open&since=${input.since}`);
      },
    }),

    // side-effecting: routes through the governed executor
    tool({
      name: "hold_order",
      capability: "order.hold",
      sideEffecting: true,
      input: z.object({ orderId: z.string(), reason: z.string() }),
      async run({ input, ctx }) {
        return ctx.http.post(`/orders/${input.orderId}/hold`, {
          reason: input.reason,
        });
      },
    }),
  ],
});

from fibric import define_connector, tool, auth
from pydantic import BaseModel

class ListOpenOrders(BaseModel):
    since: str

class HoldOrder(BaseModel):
    order_id: str
    reason: str

connector = define_connector(
    name="acme-wms",
    summary="Acme warehouse management system",
    # credentials resolved from the vault, never hard-coded
    auth=auth.api_key(header="X-Acme-Key", secret="ACME_API_KEY"),
)

# read-only: senses the world, no side effects
@connector.tool(capability="order.read")
def list_open_orders(input: ListOpenOrders, ctx) -> list[dict]:
    return ctx.http.get(f"/orders?status=open&since={input.since}")

# side-effecting: routes through the governed executor
@connector.tool(capability="order.hold", side_effecting=True)
def hold_order(input: HoldOrder, ctx) -> dict:
    return ctx.http.post(
        f"/orders/{input.order_id}/hold",
        json={"reason": input.reason},
    )

import { defineOperator, plan } from "@fibric/sdk";

export default defineOperator({
  name: "order-risk-watcher",
  model: "fibric/reason-1",

  async run({ sense, reason }) {
    // 1. SENSE: read through granted capabilities
    const orders = await sense("order.read", { since: "PT24H" });

    // 2. REASON: the base model scores which orders will slip
    const atRisk = await reason.rank(orders, {
      goal: "Find orders that will miss the carrier cutoff.",
    });

    // 3. PROPOSE: build a validated ExecutionPlan. Nothing has acted yet.
    const p = plan();
    for (const order of atRisk.filter((o) => o.willSlip)) {
      p.act("order.hold", {
        orderId: order.id,
        reason: order.why,
        // exactly-once: a retry can never double-hold the same order
        idempotencyKey: `hold:${order.id}:${order.shipBy}`,
      });
    }

    // 4. DISPOSE: the executor enforces policy + single-flight, returns receipts
    return p.submit();
  },
});

from fibric import define_operator, Plan

@define_operator(name="order-risk-watcher", model="fibric/reason-1")
def run(sense, reason):
    # 1. SENSE: read through granted capabilities
    orders = sense("order.read", since="PT24H")

    # 2. REASON: the base model scores which orders will slip
    at_risk = reason.rank(orders, goal="Find orders that will miss the carrier cutoff.")

    # 3. PROPOSE: build a validated ExecutionPlan. Nothing has acted yet.
    plan = Plan()
    for order in (o for o in at_risk if o.will_slip):
        plan.act(
            "order.hold",
            order_id=order.id,
            reason=order.why,
            # exactly-once: a retry can never double-hold the same order
            idempotency_key=f"hold:{order.id}:{order.ship_by}",
        )

    # 4. DISPOSE: the executor enforces policy + single-flight, returns receipts
    return plan.submit()

curl -X POST https://api.fibric.io/v1/plans \
  -H "Authorization: Bearer $FIBRIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operator": "order-risk-watcher",
    "steps": [
      {
        "capability": "order.hold",
        "args": { "orderId": "SO-44817", "reason": "Proof not approved; will miss cutoff." },
        "idempotencyKey": "hold:SO-44817:2026-06-13"
      }
    ]
  }'