Metadata-Version: 2.5
Name: flieber
Version: 0.0.1
Summary: The flieber command: CLI and MCP server for Flieber commerce data (actual sales, adjusted sales, forecast).
Project-URL: Homepage, https://flieber.com
Author: Flieber
License: Proprietary
Classifier: Development Status :: 1 - Planning
Classifier: Environment :: Console
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# 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.
