liber-cli 0.1.0

# liber

**An AI-agent-readable company directory.**

`liber` (Latin: "registry book") lets any company ship a structured, queryable
directory of its **people, products, repos, customers, and group chats** in a
form an AI agent can consume in one shot via a CLI called `liber`.

Inspired by Salesforce's [HERB dataset](https://huggingface.co/datasets/Salesforce/HERB),
which models a company as `employees + customers + products` with the
relations between them.

## Why

LLM agents lose a lot of context guessing at "what's the repo for product X?"
or "what's the Feishu group for customer Y?". Most companies have the answer —
in HR systems, in spreadsheets, in someone's head. `liber` is the smallest
useful shape: five JSON files + a single binary that answers those questions
deterministically.

- **For a company**: drop the JSON files into a directory, point
  `LIBER_DATA_DIR` at it, and every Claude Code / Cursor session in the
  company can answer directory questions without internet access.
- **For an agent**: one CLI with noun-then-verb subcommands, auto-JSON when
  piped, distinct exit codes, structured error JSON on stderr. No surprises.

## Install

### One-liner (macOS / Linux)

```bash
curl -sSf https://raw.githubusercontent.com/joezhoujinjing/liber/main/install.sh | sh
```

Detects your platform, downloads the latest pre-built binary from GitHub
Releases, verifies SHA256, installs to `~/.local/bin/liber`. Override with
`LIBER_VERSION=v0.1.0` or `LIBER_INSTALL_DIR=/usr/local/bin`.

### Homebrew (macOS / Linux)

```bash
brew tap joezhoujinjing/tap
brew install liber
```

### From crates.io

```bash
cargo install liber-cli
```

(Crate is `liber-cli`; the installed binary is still `liber`.)

### From prebuilt binaries — manual

Grab a tarball for your platform from
[GitHub Releases](https://github.com/joezhoujinjing/liber/releases), extract,
move the `liber` binary onto `$PATH`. Available targets:

- `aarch64-apple-darwin` (macOS, Apple Silicon)
- `x86_64-apple-darwin` (macOS, Intel)
- `aarch64-unknown-linux-gnu` (Linux, ARM64)
- `x86_64-unknown-linux-gnu` (Linux, x86_64)
- `x86_64-pc-windows-msvc` (Windows)

### From source

```bash
git clone https://github.com/joezhoujinjing/liber
cd liber
cargo install --path .
```

You need Rust 1.74+ to build from source.

## 30-second quickstart

```bash
# 1. scaffold an empty data directory
liber init mycompany ./mycompany-directory

# 2. edit the JSON files
cd mycompany-directory
$EDITOR people.json products.json repos.json customers.json chats.json

# 3. verify the data matches the schemas
LIBER_DATA_DIR=. liber validate

# 4. query it
LIBER_DATA_DIR=. liber people list
LIBER_DATA_DIR=. liber products list
LIBER_DATA_DIR=. liber repos list --visibility public
LIBER_DATA_DIR=. liber customers get example-customer
```

Or try the bundled demo company:

```bash
LIBER_DATA_DIR=examples/acme-corp liber search rocket
```

## Commands

```
liber init <slug> [path]                     scaffold an empty data dir
liber validate                               JSON-Schema-check all entity files
liber people    list [--dept NAME]
liber people    get  <name|github|alias>
liber products  list
liber products  get  <slug>
liber repos     list [--visibility V]
liber repos     get  <slug>
liber customers list
liber customers get  <slug>                  auto-enriched: products_detail + chat_ids
liber chats     list
liber chats     get  <name>
liber search    <query>                      substring across all entities
```

Global flags: `--json`, `--quiet`, `--full`, `--no-interactive`, `--data-dir <DIR>`.

Output is human-friendly on a TTY and JSON when piped (or with `--json`).
Exit codes: `0` ok, `2` validation, `4` not-found, `5` conflict, `6` data error.

## Data directory resolution

First match wins:

1. `--data-dir <path>` flag
2. `$LIBER_DATA_DIR`
3. `./.liber/` in the current directory
4. The current directory itself, if it contains the entity JSON files
5. `~/.liber/` in the home directory

If none match, `liber` exits with code 4 and a hint to run `liber init`.

## Data model

Five entity files; each one is a flat JSON document and validates against an
embedded draft-07 JSON Schema. Relations are by slug — no schema-enforced
cross-references, so agents are free to join entities however they want:

```
products[].slug   ←→   repos[].slug          (same slug = same thing)
products[].slug   ←→   customers[].related_products[]
chats keys        ←→   customers[].chats[]
```

See [docs/schema-reference.md](docs/schema-reference.md) for every field.

## Docs

- [docs/quickstart.md](docs/quickstart.md) — fill your JSONs and go in 5 minutes
- [docs/schema-reference.md](docs/schema-reference.md) — every field of every entity

## License

MIT.