Fibric. Docs
fibric.io →
v0.9 · preview
Get started

Installation

The Fibric CLI is the primary tool for driving a workspace from the terminal: connecting systems, deploying operators, attaching policies, and tailing receipts. This page covers installing the CLI, authenticating it against your workspace, initializing a project, and verifying that everything can reach the platform. If you have not seen the full loop yet, start with the quickstart.

Requirements

The CLI is distributed through npm and runs anywhere Node.js runs. You need the following before installing.

RequirementMinimumNotes
Node.js 20 or newer Check with node --version. LTS releases are recommended.
npm 10 or newer Ships with Node 20. Check with npm --version.
A Fibric account Early access Create one at app.fibric.io. One account can hold multiple workspaces.
An API key Workspace-scoped Issued from Settings → API keys in the console. Only required for non-interactive authentication.
Operating system macOS, Linux, or Windows via WSL Native Windows shells are not supported during early access; use WSL 2.
i
The console needs no install

During early access, the hosted console at app.fibric.io covers most workspace administration: connecting systems, reading receipts, and managing keys. The CLI is required only when you deploy operators or connectors from code.

Install the CLI

Install the CLI globally so the fibric command is available in any project.

bash
npm install -g @fibric/cli

# confirm the binary is on your PATH
fibric --version

Projects that define operators or connectors in code also need the SDK as a local dependency. You do not need it to follow this page; fibric init adds it for you in the next section.

bash
# per-project SDK, installed inside a project directory
npm install @fibric/sdk

Authenticate

The CLI supports two authentication modes. Use the browser flow on a development machine; use an API key in CI and other non-interactive environments.

Browser flow

fibric auth login opens your default browser, asks you to sign in to your Fibric account, and writes a short-lived credential to ~/.fibric/credentials. If your account has more than one workspace, the CLI prompts you to pick one; you can switch later with the FIBRIC_WORKSPACE variable or the --workspace flag on any command.

bash
fibric auth login
$ fibric auth login Opening https://app.fibric.io/cli/authorize in your browser… Waiting for confirmation… ✓ signed in as jordan@acme.example workspace acme-ops (default)

API key for CI

In CI, set an API key in the environment instead. A key is scoped to one workspace and can be rotated from the console at any time. When FIBRIC_API_KEY is set, the CLI uses it and skips the credential file entirely.

bash
export FIBRIC_API_KEY="sk_live_…"
export FIBRIC_WORKSPACE="acme-ops"
VariableRequiredDescription
FIBRIC_API_KEY In CI Workspace-scoped API key from Settings → API keys. Takes precedence over browser-flow credentials when set.
FIBRIC_WORKSPACE No Workspace slug to target, for example acme-ops. Overrides the default chosen during fibric auth login.
!
Keep keys out of source

Store the key in your CI provider's secret store or a secrets manager, never in the repository. If a key leaks, rotate it from the console; the old key stops working immediately.

Initialize a workspace project

fibric init scaffolds a project directory that is bound to your workspace: a fibric.json manifest, a TypeScript setup with @fibric/sdk installed, and an empty operators/ directory. Run it inside a new or existing directory.

bash
mkdir acme-ops && cd acme-ops
fibric init
$ fibric init workspace acme-ops created fibric.json created operators/ installed @fibric/sdk ✓ project initialized

The manifest records the workspace slug so that every subsequent command in this directory targets the right tenant without flags. Everything you deploy from this project carries your tenant_id on every envelope, row, and receipt; see Tenancy & isolation for how that wall is enforced.

Verify the installation

fibric whoami confirms that the CLI is installed, authenticated, and pointed at the workspace you expect. Run it before anything else; if this works, every other command will reach the platform.

bash
fibric whoami
$ fibric whoami workspace acme-ops tenant_id t_8f2a…c901 (walled off) plan preview auth api key (FIBRIC_API_KEY) ✓ authenticated

Upgrade and uninstall

The CLI is versioned with the platform; during the v0.9 preview, upgrade whenever a new release is announced in the changelog.

bash
# upgrade to the latest release
npm install -g @fibric/cli@latest

# remove the CLI entirely
npm uninstall -g @fibric/cli

Uninstalling does not delete ~/.fibric/credentials. Remove that file by hand if you are decommissioning a machine, and rotate any API keys the machine held.

Troubleshooting

The three failures below account for nearly all installation problems.

SymptomCauseFix
fibric: command not found The npm global bin directory is not on your PATH. Run npm prefix -g and add its bin subdirectory to PATH in your shell profile, then open a new shell.
401 unauthorized on any command The API key was rotated or revoked, or a stale FIBRIC_API_KEY is shadowing a valid login. Issue a fresh key from Settings → API keys and update the environment, or unset FIBRIC_API_KEY and run fibric auth login again.
EACCES during npm install -g The npm global prefix points at a directory your user cannot write, commonly a system location. Set a user-owned prefix with npm config set prefix ~/.npm-global, add ~/.npm-global/bin to PATH, and reinstall. Do not install with sudo.

Next steps