flieber-cli

flieber is the command-line and agent interface to Flieber's commerce data. It gives developers, scripts and AI agents (Claude, Cursor, Lovable, custom agents) one stable, versioned way to read a tenant's:

• actual sales: what each channel recorded, per product × store;
• adjusted sales: actuals corrected for stockouts, outliers and price effects, used as the forecast input;
• forecast: expected demand per product × store, from today on (meta.last_nonzero_forecast_period is the latest period with a non-zero forecast; core-service exposes no horizon).

Status: v0 in design. The architecture and contract v1 are ADR-0001 (Accepted). The code arrives through the issues in the Linear project "Data Layer Product (Vibee) | Backend" (team Flieber AI - R&D, milestone M3). Only the 0.0.1 placeholder is published so far.

Shape

One Python package: a shared core, and several surfaces built on it.

            ┌──────────────────── flieber (Python package) ────────────────────┐
            │  core: auth · GraphQL client · versioned tool contract · shaping  │
            └──────┬──────────────────────┬───────────────────────┬────────────┘
                   │                      │                       │
          CLI  `flieber …`      MCP (local)  `flieber mcp`   MCP (hosted)  `flieber mcp --http`
          humans & scripts      stdio, launched by           container behind a stable URL,
                                Claude / Cursor              used by the self-serve product

• Core
  • Authentication with a Flieber public-API key (FLIEBER_API_KEY, or the OS keyring or a 0600 config file, written by flieber auth login).
  • A client for core-service's public GraphQL API.
  • The versioned tool contract: one definition per capability. It drives both the CLI command and the MCP tool, so the two cannot drift (a ratchet test checks the parity, ADR-0001 §7).
  • Output shaping for humans (tables) and for LLMs (compact {columns, rows}, point caps, pagination).
• CLI: flieber status, flieber listings, flieber products, flieber mapping, flieber sales, flieber adjusted, flieber forecast, flieber trends. JSON output is available for scripts.
• MCP: the same capabilities as MCP tools, over stdio (local) or streamable HTTP (hosted, stateless). The hosted mode forwards the caller's own API key and stores nothing.

Design rule: customers bind to this contract, never to the raw GraphQL schema. The backend behind it may change; the contract changes only through versioning.

Principles and how to contribute

• What the project is, and the rules no change may break (the three signals, least privilege, no secrets at rest, bounded cost and output, honest results): docs/00-invariants.md. It ranks above everything else.
• How work is done (proof before done, test-first, ports and adapters, one authoritative path per process): AGENTS.md. It applies to humans and agents alike.
• Decisions: docs/adr/.

Tooling (v0)

• Python ≥ 3.12.
• Packaging with uv and pyproject.toml; installable as uvx flieber … / pipx install flieber.
• Tests with pytest, run as uv run pytest (ADR-0001 §8).

flieber is published on PyPI (the 0.0.1 placeholder, 2026-09-29, CI pipeline 2894945075). Releases, the version scheme and the changelog rules: docs/release.md.

Development

uv sync                                        # Python ≥ 3.12, with the dev dependency group
uv run pytest                                  # tests never reach the network
uv run ruff check src tests scripts && uv run ruff format --check src tests scripts
uv run python -m flieber.contract.document --write   # after a contract change; review the diff
python scripts/pin_schema.py <core-service ref>      # re-pin core-service's schema
scripts/release_check.sh                       # build and verify dist/ exactly as CI does (docs/release.md)
uv run flieber --env qa ping                   # the proof run against QA (needs a QA key)

How work is done here, including what counts as proof, is in AGENTS.md.

Related

• core-service: the public GraphQL API at /api/graphql, and public-API keys with per-resource grants.
• flieber-build-front: the self-serve portal, which issues API keys and shows the MCP and CLI configuration.
• ai-lab tools/flieber_agent_tunnel: the existing ask_flieber MCP server. It is the reference for the streamable-HTTP MCP skeleton and the Clerk OAuth pieces.