# Synorb CLI

The official `@synorb/cli` is a small command-line client for agents and local
developer workflows. It uses the same bearer-key and JSON contracts as the
[REST API](https://synorb.com/openapi.json). Content and discovery commands are
read-only; the `billing` subcommand is the one exception and is a hosted
handoff, described under Commands.

The CLI authenticates with a Synorb Key only. Synorb's
[OAuth 2.0 flow](https://synorb.com/auth) is a REST/MCP credential; there is
no CLI login subcommand yet, so do not expect one.

## Install or run from source

Install the published package from npm:

```bash
npm install -g @synorb/cli
```

The source is also available on GitHub at
[Synorb/synorb-cli](https://github.com/Synorb/synorb-cli) for local
development:

```bash
git clone https://github.com/Synorb/synorb-cli
cd synorb-cli
node src/cli.js --help
```

## Commands

```bash
synorb connect --save
synorb profile
synorb stream-search "AI infrastructure"
synorb manifests --stream-id 17810211877157441 --days 7
```

`connect` asks Synorb for a demo key. With `--save`, it stores the
returned demo key at `~/.config/synorb/config.json` with restrictive file
permissions. In CI, set `SYNORB_TOKEN` instead. Override the API endpoint with
`SYNORB_API_URL` or `--api-url`.

The CLI emits JSON by default (`--pretty` formats it) and sends keys only in the
`Authorization: Bearer` header. It has no content-mutation and no
Beacon-mutation commands. Content retrieval can consume Manifest usage allowance; use
`stream-search`, `profile`, or `manifests --mode count` for discovery and
preflight work.

### Billing commands

```bash
synorb billing checkout --plan individual|professional|startup [--cycle monthly|annual] [--open]
synorb billing portal [--open]
synorb billing status
```

`checkout` and `portal` POST to `/api/billing/checkout-session` and
`/api/billing/portal-session` and return a hosted Stripe URL; `--open` launches
it in a browser. They start a payment flow — no charge happens in the CLI, and
nothing is charged without the hosted page being completed by a human. An agent
running unattended should not invoke them.

Source package: https://github.com/Synorb/synorb-cli

## Ecosystem status

The published CLI is the official npm client, and
[`synorb` on PyPI](https://pypi.org/project/synorb/) (`pip install synorb`) is
the official Python client. The repository's `sdk/` package is a separate,
legacy, source-only sync-ontology helper and is not a Synorb Key client. Use the
[OpenAPI contract](https://synorb.com/openapi.json) or the
[agent ecosystem manifest](https://synorb.com/agent-ecosystem.json) when
generating a client for any other language.