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 daily demand per product × store, about 12–14 months ahead.

Status: v0 in design. This README is the charter. The code arrives through the issues in the Linear project "Vibee Backend: v0 → greenfield gate" (team Flieber AI - R&D, milestone M3).

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 a 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 can never drift.
  • Output shaping for humans (tables) and for LLMs (compact {columns, rows}, point caps, pagination).
• CLI: flieber status, flieber listings, 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

• The three signals are never mixed.
  • Adjusted sales never include today or later.
  • The forecast never includes dates before today.
  • Actual sales come only from the sales-analytics fields.
• Least privilege: the key's grants in core-service decide what can be read. The tool reports a missing grant by name.
• No secrets at rest in the hosted mode. Logs carry only a hash prefix of the key.
• Honest errors: rate limits, missing grants and stale data are reported plainly, with a hint about what to do next.

Tooling (v0)

• Python 3.12.
• Packaging with uv and pyproject.toml; installable as uvx flieber … / pipx install flieber.
• Tests with pytest.

The PyPI names flieber and flieber-cli were free on 2026-09-29.

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.