offline-cli 0.0.0

# Offline Protocol CLI (`offline`)

[![CI](https://github.com/Offline-Protocol/CLI/actions/workflows/ci.yml/badge.svg)](https://github.com/Offline-Protocol/CLI/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Release](https://img.shields.io/github/v/release/Offline-Protocol/CLI?display_name=tag)](https://github.com/Offline-Protocol/CLI/releases)

One CLI to build offline-first apps on the Offline Protocol ecosystem — and
the MCP server that makes the whole ecosystem **AI-native**.
```bash
offline login                                       # authenticate with the developer portal
offline create offline-social-network --name my-app --yes
offline create --prompt "local event chat app" --platform react-native --name pulse --yes
offline doctor                                      # validate your environment
offline mcp serve                                   # MCP server for AI agents (stdio)
```

## What's inside

| Crate | Purpose |
|---|---|
| `crates/offline-cli` | The `offline` binary: login, create, init, add, plan, doctor, update, registry, skills, mcp |
| `crates/offline-registry` | Knowledge core: packages, skills, workflows, templates — embedded, fully offline |
| `crates/offline-generator` | Tera-based project scaffolding (used by `create` and MCP `scaffold_project`) |
| `crates/offline-mcp` | Model Context Protocol server: plan, scaffold, and integrate Offline Protocol components |
| `crates/offline-registry/registry/` | Content: packages, skills, workflows, starter templates |

### Workflows & templates

| Workflow | Templates |
|---|---|
| `offline-social-network` | `react-native-social`, `nextjs-social`, `react-vite-social` |
| `nearby-chat` | `react-native-mesh-app` |
| `group-messaging` | `react-native-mesh-app` |
| `local-marketplace` | `react-native-mesh-app` |
| `referral-system` | `nextjs-social` |

## Install

The installed command is always `offline`.

**npm (recommended):**

```bash
npm install -g @offline-protocol/cli
offline --version
```

**crates.io:**

```bash
cargo install offline-cli --locked
offline --version
```

**From source (developers):**

```bash
git clone https://github.com/Offline-Protocol/CLI.git
cd CLI
cargo install --path crates/offline-cli
offline --version
```

**From GitHub Releases** (archives + `SHA256SUMS`):

1. Download the archive for your platform from
   [Offline-Protocol/CLI releases](https://github.com/Offline-Protocol/CLI/releases)
2. Verify with `SHA256SUMS` or the matching `.sha256` file
3. Extract and put `offline` on your `PATH`
4. Run `offline doctor` and `offline update`

Maintainer release process: [docs/RELEASING.md](docs/RELEASING.md).

Homebrew distribution is still planned.

## Command reference

Quick map of top-level commands. Full descriptions, flags, and examples:
**[docs/COMMANDS.md](docs/COMMANDS.md)**.

| Command | Purpose |
|---|---|
| `offline login` / `logout` / `whoami` | Interactive auth (localhost callback + poll); logout revokes the key server-side when possible |
| `offline create` | Scaffold from workflow, template, or `--prompt`; runs `npm install` and starts the dev server (Metro for React Native) unless `--skip-setup` |
| `offline plan` | Plan only (workflow + packages + optional architecture docs) |
| `offline init` | Wire `offline.config.json`, `.mcp.json`, `AGENTS.md` into an existing app |
| `offline add <package>` | Add package (+ transitive requires) to `package.json` |
| `offline doctor` | Toolchain + auth + API reachability checks |
| `offline update` | Check GitHub Releases for a newer CLI |
| `offline registry …` | List / search / show packages, workflows, skills, templates, capabilities; export `llms.txt` |
| `offline skills list` / `show` | List or read an integration skill |
| `offline mcp serve` | Run the MCP server (stdio) |
| `offline mcp install <client>` | Print client config (`cursor`, `claude-desktop`, `vscode`, `claude-code`) |
| `offline mcp tools` | List MCP tools |
| `offline completions <shell>` | Shell completions |

Every informational command supports `--json`. Config: `~/.offline/config.json` (0600).
Overrides: `OFFLINE_API_KEY`, `OFFLINE_API_BASE`, `OFFLINE_ENV` (`prod` or `dev`/`local`),
`OFFLINE_PORTAL_BASE`, `OFFLINE_CONFIG_DIR`, `OFFLINE_REGISTRY_DIR`,
`OFFLINE_CALLBACK_PORT` (localhost login callback; default `9876`).

## For AI agents (MCP)

The MCP server is **local stdio** inside the CLI — no separate cloud deploy.
Agents plan and integrate Offline Protocol components via tools (not from memory).

### Set up Cursor / Claude

```bash
# Pick ONE client (do not use | — the shell treats it as a pipe):
offline mcp install cursor
offline mcp install claude-desktop
offline mcp install vscode
offline mcp install claude-code

# Claude Code shortcut:
claude mcp add offline-protocol -- offline mcp serve
```

Paste the printed JSON into the client’s MCP config. Ensure `offline` is on `PATH`,
then reload the agent / MCP session.

### Ask the agent to create a project

Use **Agent mode** and a prompt like:

```text
Using the offline-protocol MCP only (do not invent package names or SDK APIs):

1. Call generate_architecture with my idea.
2. Follow nextActions.
3. Call scaffold_project with name="festival-pulse" and platform="react-native".
4. Call get_skill for every skill listed before writing Offline Protocol code.

Idea: nearby festival chat with Offline ID login and BLE mesh messaging
```

Or use the MCP prompt **`plan-app`** with `description`, optional `platform`, and `name`.

**Flow:** `generate_architecture` → `scaffold_project` (new) or `integrate_packages` + `init_project` (existing) → `get_skill` → app code.

Full tool list and rules: [docs/MCP.md](docs/MCP.md).

## Development

```bash
cargo build --workspace
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all -- --check

# live registry content (not the embedded copy):
OFFLINE_REGISTRY_DIR=./crates/offline-registry/registry cargo run -p offline-cli -- registry list

# local API gateway (typically :3010):
OFFLINE_ENV=dev offline login
```

### CI & releases

| Workflow | Trigger | What it does |
|---|---|---|
| `.github/workflows/ci.yml` | PR + push to `main` | fmt, clippy, tests; release-build smoke on `main` |
| `.github/workflows/release.yml` | tag `v*` or manual bump | Bumps version, updates `CHANGELOG.md`, builds binaries, publishes GitHub Release |

Manual release: Actions → **Release** → bump `patch`/`minor`/`major` (needs `RELEASE_PAT`).
Or push a tag: `git tag v0.1.2 && git push origin v0.1.2` (add a `CHANGELOG.md` section for that version first if you skip the bump job).

Release notes on GitHub come from the matching `## [x.y.z]` section in [`CHANGELOG.md`](CHANGELOG.md), which `git-cliff` refreshes during the bump job (`cliff.toml`).

## Documentation

- [docs/COMMANDS.md](docs/COMMANDS.md) — full command reference
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — crates, planner, MCP integrate loop
- [docs/REGISTRY.md](docs/REGISTRY.md) — registry schema and authoring
- [docs/MCP.md](docs/MCP.md) — MCP tools, agent prompts, local vs hosted
- [docs/AUTH.md](docs/AUTH.md) — device-flow login / logout
- [CHANGELOG.md](CHANGELOG.md) — release history

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, PR expectations, and registry
guidelines. Please follow the [Code of Conduct](CODE_OF_CONDUCT.md).

Security reports: [SECURITY.md](SECURITY.md) (do not file public issues for
vulnerabilities).

## License

Licensed under the [Apache License, Version 2.0](LICENSE).
See [NOTICE](NOTICE) for copyright attribution.

## Status

Shipped: device-flow auth, deterministic planning, Tera scaffolds, MCP **plan + scaffold + integrate**,
CI, multi-platform GitHub Releases, `offline update`.

Not yet: hosted MCP (Streamable HTTP), hosted registry refresh, Homebrew tap,
official crates.io publish (install via git or GitHub Releases until then),
usage analytics.