npm - @senso-ai/cli - Versions diffs - 0.11.1 → 0.14.0 - Mend

@senso-ai/cli 0.11.1 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -1,444 +1,243 @@
 # Senso CLI
-> Infrastructure for the Agentic Web
+[![Testing](https://github.com/AI-Template-SDK/senso-user-cli/actions/workflows/testing.yml/badge.svg)](https://github.com/AI-Template-SDK/senso-user-cli/actions/workflows/testing.yml)
+[![npm version](https://img.shields.io/npm/v/@senso-ai/cli.svg)](https://www.npmjs.com/package/@senso-ai/cli)
+[![npm downloads](https://img.shields.io/npm/dm/@senso-ai/cli.svg)](https://www.npmjs.com/package/@senso-ai/cli)
+[![Node](https://img.shields.io/node/v/@senso-ai/cli.svg)](https://nodejs.org)
+[![License: AGPL v3](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
-The official command-line interface for [Senso](https://docssenso.ai). Search your knowledge base, manage content, and control your entire Senso organization — directly from the terminal.
+> Infrastructure for the Agentic Web
-Built for **AI agents** (Claude Code, Gemini CLI, Codex) and **developers** who want fast, scriptable access to their Senso workspace.
+The command-line interface for [Senso](https://docs.senso.ai). Search your
+knowledge base, manage content, run the generation engine and read your GEO
+analytics — from a terminal, a script, or an AI agent.
----
+Built for **agents** (Claude Code, Gemini CLI, Codex) as much as for people:
+stdout carries only the payload, `--output json` is available on every command,
+and failures exit with a code that says what went wrong.
-## Quick Install
+## Install
-Requires **Node.js 18+**. Works on **Linux**, **macOS**, and **Windows**.
+Requires **Node.js 20.12 or newer**. Works on Linux, macOS and Windows.
 ```bash
 npm install -g @senso-ai/cli
-```
-Verify it works:
-```bash
 senso --version
 ```
-> **One-off usage** — If you just want to try it without installing globally:
->
-> ```bash
-> npx @senso-ai/cli --help
-> ```
-## Quick Start
-### 1. Authenticate
-Get an API key from [docs.senso.ai](https://docs.senso.ai), then:
-```bash
-senso login
-```
-The interactive prompt will walk you through pasting your key and verifying it against your organization.
-Alternatively, set an environment variable (useful for CI and AI agents):
+Or without installing:
 ```bash
-export SENSO_API_KEY=tgr_your_key_here
+npx @senso-ai/cli --help
 ```
-### 2. Search your knowledge base
+## 60 seconds
 ```bash
-senso search "What are the current mortgage rates?"
-```
+# 1. Authenticate. Get a key from https://docs.senso.ai
+export SENSO_API_KEY=tgr_your_key_here     # or run: senso login
-### 3. List your content
+# 2. Ask your knowledge base a question
+senso search "what is our refund policy?"
-```bash
-senso content list
+# 3. The same thing, for a program
+senso search "what is our refund policy?" --output json | jq -r .answer
 ```
-That's it. Every endpoint in the Senso Org API is available as a CLI command.
+That third line is the point of this tool. There is no `--quiet` in it because
+none is needed: stdout carries the payload and nothing else.
----
+## Using it from an agent
-## Platform Support
+The whole contract, in one place.
-| Platform | Supported | Config Location |
-|----------|-----------|-----------------|
-| **Linux** | Node 18+ | `~/.config/senso/config.json` |
-| **macOS** | Node 18+ | `~/Library/Preferences/senso/config.json` |
-| **Windows** | Node 18+ | `%APPDATA%\senso\config.json` |
+**Streams.** stdout is the payload. Everything else — progress, warnings,
+errors, the banner — goes to stderr. Redirecting stdout to a file gives you data
+or an empty file, never a sentence you have to strip.
-Config paths are handled automatically via XDG-compatible directories. The config file stores your API key, org info, and update check timestamps with owner-only permissions (`0600`).
+**Formats.** Every command takes `--output`:
----
+| Format  | For                | Notes                                           |
+| ------- | ------------------ | ----------------------------------------------- |
+| `json`  | scripts and agents | The API payload, unmodified. Implies `--quiet`. |
+| `table` | reading a list     | Aligned columns; long cells truncated.          |
+| `plain` | reading one thing  | Complete and untruncated. The default.          |
-## Usage with AI Agents
+**Exit codes.** Branch on these rather than on message text.
-The CLI is designed as a first-class tool for AI LLM agents. Pass `--output json` to get structured output and `--quiet` to suppress banners:
-```bash
-# Claude Code / Gemini CLI / Codex can call this directly
-senso search "customer refund policy" --output json --quiet
-# Pass API key inline (no config file needed)
-senso search "billing FAQ" --api-key tgr_... --output json --quiet
-```
-### Auth Priority
-The CLI resolves credentials in this order:
-1. `--api-key` flag (highest priority)
-2. `SENSO_API_KEY` environment variable
-3. `~/.config/senso/config.json` stored key
-4. Interactive prompt (first-run only)
-For non-interactive use (CI, agents), set the env var or pass the flag.
----
-## Commands
-### Authentication
-```
-senso login                          Authenticate with Senso (interactive)
-senso logout                         Remove stored credentials
-senso whoami                         Show current org and auth status
-```
+| Code | Meaning                        | What to do           |
+| ---- | ------------------------------ | -------------------- |
+| 0    | Success                        | —                    |
+| 1    | The API or the runtime refused | Read the message     |
+| 2    | Usage error                    | Fix the command line |
+| 3    | Authentication                 | Fix the credential   |
+| 4    | Not found                      | Check the ID         |
+| 5    | Network failure or timeout     | Retry                |
-### Search
+**Errors are structured too.** Under `--output json`, a failure writes JSON to
+stderr and leaves stdout empty:
+```json
+{
+  "error": {
+    "code": "unauthorized",
+    "message": "Authentication failed: the API key was rejected.",
+    "status": 401,
+    "hint": "Run `senso login` to store a new key, or check SENSO_API_KEY."
+  }
+}
 ```
-senso search <query>                 Semantic search with AI-generated answer + source chunks
-senso search context <query>         Chunks only (no AI answer, faster)
-senso search content <query>         Content IDs only (deduplicated)
-```
-Options: `--max-results <n>`
-### Content
-```
-senso content list                   List all knowledge base items
-senso content get <id>               Get full content detail by ID
-senso content versions <id>          List version history for a content item
-senso content delete <id>            Delete content (knowledge base + external)
-senso content unpublish <id>         Unpublish and revert to draft
-senso content verification           List items in verification workflow
-senso content verification-counts    Counts by status + published-domain summaries
-senso content reject <versionId>     Reject a content version
-senso content restore <versionId>    Restore rejected version to draft
-senso content owners <id>            List owners of a content item
-senso content set-owners <id>        Replace owners (--user-ids)
-senso content remove-owner <id> <userId>  Remove a single owner
-```
-Options: `content list` supports `--limit`, `--offset`, `--search`, `--sort`. `content verification` supports `--limit`, `--offset`, `--search`, `--status`, `--substatus`. `content reject` supports `--reason`.
-### Generated Content (GEO)
-```
-senso generated-content list         List published or draft generated content (--status published|drafts)
-senso generated-content get <id>     Get a generated content item with its rendered body
-```
-Options: `generated-content list` supports `--status`, `--limit`, `--offset`, `--search`.
-### Content Generation
-```
-senso generate settings              Get generation settings
-senso generate update-settings       Update generation settings (--data)
-senso generate sample                Generate sample for a prompt; waits for async job by default (--prompt-id, --content-type-id, --no-wait)
-senso generate run                   Trigger a content engine run (--prompt-ids)
-```
-### Content Engine
-```
-senso engine publish                 Publish content to external destinations (--data)
-senso engine draft                   Save content as draft for review (--data)
-```
-### Tracked Competitors & Sources
-```
-senso competitors list               List tracked competitors
-senso competitors add                Add a competitor (--name, --url)
-senso competitors suggest            Get AI-generated competitor suggestions
-senso competitors batch-add          Add up to 50 competitors (--data)
-senso competitors update <id>        Update a competitor (--name, --url)
-senso competitors delete <id>        Remove a competitor
-senso tracked-sources list           List citation-classification rules
-senso tracked-sources add            Add a rule (--pattern, --match-type, --tier)
-senso tracked-sources update <id>    Replace a rule (--pattern, --match-type, --tier)
-senso tracked-sources delete <id>    Remove a rule
-```
-Options: `tracked-sources add`/`update` support `--category`, `--label`, `--priority`; `update` also supports `--active`/`--no-active`. `--match-type` is one of `domain | host | path_prefix | exact_url`; `--tier` is one of `primary | tracked | secondary`.
-### Ingestion
-```
-senso ingest upload <files...>       Upload files to knowledge base (up to 10)
-senso ingest reprocess <contentId> <file>  Re-ingest content with new file
-```
-### Brand Kit & Content Types
-```
-senso brand-kit get                  Get brand kit guidelines
-senso brand-kit set                  Create or replace brand kit (--data)
-senso content-types list             List content types
-senso content-types create           Create a content type (--data)
-senso content-types get <id>         Get content type by ID
-senso content-types update <id>      Update a content type (--data)
-senso content-types delete <id>      Delete a content type
-```
-Options: `content-types list` supports `--limit`, `--offset`.
-### Prompts
-```
-senso prompts list                   List prompts (geo questions)
-senso prompts create                 Create a prompt (--data)
-senso prompts get <promptId>         Get prompt with run history
-senso prompts delete <promptId>      Delete a prompt
-```
-Options: `prompts list` supports `--limit`, `--offset`, `--search`, `--sort`.
-### Organization
-```
-senso org get                        Get organization details
-senso org update                     Update organization details (--data)
-senso users list                     List users
-senso users add                      Add a user (--data)
-senso users get <userId>             Get user details
-senso users update <userId>          Update a user's role (--data)
-senso users remove <userId>          Remove a user
-senso users set-current <userId>     Set org as current for a user
-senso api-keys list                  List API keys
-senso api-keys create                Create API key (--data)
-senso api-keys get <keyId>           Get API key details
-senso api-keys update <keyId>        Update API key (--data)
-senso api-keys delete <keyId>        Delete API key
-senso api-keys revoke <keyId>        Revoke API key
-senso members list                   List organization members
-```
-Options: `users list` supports `--limit`, `--offset`. `api-keys list` supports `--limit`, `--offset`. `members list` supports `--limit`, `--offset`, `--search`, `--sort`.
-### Run Configuration
-```
-senso run-config models              Get configured AI models
-senso run-config set-models          Set AI models (--data)
-senso run-config schedule            Get run schedule (days of week)
-senso run-config set-schedule        Set run schedule (--data)
-```
-### Notifications
-```
-senso notifications list             List notifications
-senso notifications read <id>        Mark notification as read
-```
-Options: `notifications list` supports `--limit`, `--offset`, `--unread-only`.
-### CLI Management
-```
-senso update                         Update to the latest version
-senso --version                      Show current version
-senso --help                         Show help
-```
----
-## Global Options
+`error.code` is stable. Messages may be reworded; codes are part of the
+interface.
-| Flag | Description |
-|------|-------------|
-| `--api-key <key>` | Override API key (or set `SENSO_API_KEY` env var) |
-| `--base-url <url>` | Override API base URL (default: `https://apiv2.senso.ai/api/v1`) |
-| `--output <format>` | Output format: `json`, `table`, or `plain` (default: `plain`) |
-| `--quiet` | Suppress banners and non-essential output |
-| `--no-update-check` | Skip version check (or set `SENSO_NO_UPDATE_CHECK=1`) |
-| `-v, --version` | Show version |
-| `-h, --help` | Show help |
+**Environment.**
----
+| Variable                  | Purpose                                                      |
+| ------------------------- | ------------------------------------------------------------ |
+| `SENSO_API_KEY`           | The API key, if you would rather not run `senso login`       |
+| `SENSO_BASE_URL`          | Point at a different API                                     |
+| `SENSO_CONFIG_DIR`        | Relocate the config file (per-project credentials, or tests) |
+| `SENSO_DEBUG=1`           | Log every request and its status to stderr, key redacted     |
+| `SENSO_NO_UPDATE_CHECK=1` | Never check npm for a newer version                          |
+| `NO_COLOR`                | Disable color (any value)                                    |
-## Output Formats
-**Plain** (default — human-friendly):
+**Teaching an agent to use Senso.** The official agent skills install in one
+command:
+```bash
+senso skills install --all
 ```
-$ senso search "mortgage rates"
-Answer: Based on our knowledge base, current mortgage rates are...
-Found 3 results:
-  1. Mortgage Rate Overview
-     Content: Fixed-rate mortgages currently average...
-     ID: cnt_abc123
-```
+## Commands
-**JSON** (for AI agents and scripting):
+**[Full command reference →](docs/reference/commands.md)** — every command,
+argument and flag, generated from the CLI itself.
+| Group                                                                    | What it does                                                        |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| `login` `logout` `whoami`                                                | Authentication and the current organization                         |
+| `search`                                                                 | Ask the knowledge base, with an AI answer, raw chunks, or streaming |
+| `kb` `ingest` `content`                                                  | The knowledge base: upload, browse, organize, verify                |
+| `ctas`                                                                   | Call-to-action cards on published pages                             |
+| `generate` `engine` `generated-content` `destinations` `publish-records` | Generate content and publish it                                     |
+| `analytics`                                                              | GEO metrics for your own organization                               |
+| `industries`                                                             | Competitive intelligence (needs a partner key)                      |
+| `prompts` `questions` `competitors` `tracked-sources`                    | What gets monitored                                                 |
+| `brand-kit` `content-types` `product-lines` `tags`                       | How content is shaped                                               |
+| `org` `users` `members` `roles` `permissions` `api-keys` `credits`       | Organization administration                                         |
+| `run-config`                                                             | Which models run, and on which days                                 |
+| `skills`                                                                 | Install the Senso agent skills                                      |
+| `update`                                                                 | Update this CLI                                                     |
+A few worth knowing about:
-```
-$ senso search "mortgage rates" --output json
-{
-  "answer": "Based on our knowledge base...",
-  "results": [
-    {
-      "title": "Mortgage Rate Overview",
-      "chunk_text": "Fixed-rate mortgages currently average...",
-      "content_id": "cnt_abc123"
-    }
-  ]
-}
+```bash
+senso search "..." --output json          # answer + sources, for a program
+senso search stream "..."                 # tokens as they arrive
+senso ingest upload ./policy.pdf          # into the knowledge base
+senso analytics summary                   # headline GEO metrics
+senso analytics glossary                  # what every metric means
 ```
-**Table** (for listing resources):
+### Reading the analytics numbers
-```
-$ senso content list --output table
+`senso analytics` reports how often AI models name your brand and which pages
+they cite. The metrics are easy to misread, so
+**[docs/analytics.md](docs/analytics.md)** states what each one divides by. The
+short version:
-ID           Title                    Status
-cnt_abc123   Mortgage Rate Overview   published
-cnt_def456   Variable Rate Products   draft
-```
+- **Share of Voice** divides by mentions of _every_ brand the models named, not
+  just your tracked competitors.
+- **Citation Rate** and **Coverage** divide by answers that carried at least one
+  citation. **Citation Share** divides by total citation instances. They are
+  different metrics on different denominators.
+- A metric shown as `—` means _not measured_ — its denominator was zero. That is
+  not the same as 0%.
+- `analytics answers` is a snapshot, not a window: narrowing the dates hides
+  results rather than returning older ones.
----
+`senso analytics glossary` is the canonical definition of each metric, its
+denominator and its gotcha, straight from the API.
-## Auto-Update
+## Configuration
-The CLI checks for new versions once every 24 hours (via GitHub releases) and shows a notice on stderr if an update is available:
-```
-╭──────────────────────────────────────────────╮
-│                                              │
-│  Update available! 0.1.0 → 0.2.0            │
-│                                              │
-│  Run senso update to update                  │
-│                                              │
-╰──────────────────────────────────────────────╯
-```
+`senso login` stores your key in a JSON file with owner-only permissions:
-Update notices are written to `stderr` so they won't interfere with `--output json` piped to other programs.
+| Platform | Location                                  |
+| -------- | ----------------------------------------- |
+| Linux    | `~/.config/senso/config.json`             |
+| macOS    | `~/Library/Preferences/senso/config.json` |
+| Windows  | `%APPDATA%\senso\Config\config.json`      |
-To disable: `--no-update-check` or `export SENSO_NO_UPDATE_CHECK=1`.
+Set `SENSO_CONFIG_DIR` to put it somewhere else. Credentials resolve in this
+order: `--api-key`, then `SENSO_API_KEY`, then the config file. `senso login`
+needs a terminal; in CI or an agent, set the environment variable.
----
+The CLI checks npm for a newer version once a day and prints a notice on stderr.
+`senso update` upgrades it; `SENSO_NO_UPDATE_CHECK=1` turns the check off.
 ## Development
 ```bash
-# Clone the repo
-git clone https://github.com/AI-Template-SDK/senso-user-cli.git
-cd senso-user-cli
-# Install dependencies
-npm install
-# Run in dev mode (TypeScript directly via tsx)
-npm run dev -- search "test query"
-# Build (single ESM bundle via tsup)
-npm run build
-# Run the built version
-node dist/cli.js --help
-# Run tests
-npm test
+nvm use                 # Node 22, per .nvmrc
+npm ci
+make all                # everything CI runs
 ```
-### Project Structure
+`make all` is the whole pipeline, and CI invokes the same targets in the same
+order — a green `make all` and a green pipeline cannot mean different things.
-```
-src/
-├── cli.ts                 # Entry point — arg parsing, command dispatch
-├── commands/              # One file per command group
-│   ├── auth.ts            # login, logout, whoami
-│   ├── search.ts          # search, search context, search content
-│   ├── content.ts         # CRUD + versions + verification + owners
-│   ├── generated-content.ts  # GEO generated content (list, get)
-│   ├── generate.ts        # content generation settings + triggers
-│   ├── engine.ts          # publish, draft
-│   ├── competitors.ts     # tracked competitors CRUD + suggest
-│   ├── tracked-sources.ts # citation-classification rules CRUD
-│   ├── ingest.ts          # upload, reprocess (with S3 upload)
-│   ├── brand-kit.ts       # get, set
-│   ├── content-types.ts   # CRUD
-│   ├── prompts.ts         # CRUD
-│   ├── org.ts             # get, update
-│   ├── users.ts           # CRUD + set-current
-│   ├── api-keys.ts        # CRUD + revoke
-│   ├── members.ts         # list
-│   ├── run-config.ts      # models, schedule
-│   ├── notifications.ts   # list, read
-│   └── update.ts          # self-update
-├── lib/
-│   ├── api-client.ts      # HTTP wrapper (native fetch, X-API-Key auth)
-│   ├── config.ts          # Config read/write (~/.config/senso/)
-│   ├── output.ts          # json/table/plain formatting
-│   └── version.ts         # Reads version from package.json
-└── utils/
-    ├── logger.ts          # Colored log helpers (picocolors)
-    ├── branding.ts        # ASCII logo, gradient banner, boxed panels
-    └── updater.ts         # GitHub releases version check
-```
+| Stage      | Command          | What it checks                                            |
+| ---------- | ---------------- | --------------------------------------------------------- |
+| Lint       | `make lint`      | ESLint (type-aware) and Prettier                          |
+| Typecheck  | `make typecheck` | `tsc --noEmit` over src, tests and scripts                |
+| Security   | `make security`  | `npm audit`, semgrep, and gitleaks over the full history  |
+| Unit       | `make unit`      | Unit, command and policy tests, behind a coverage gate    |
+| End-to-end | `make e2e`       | The built bundle, as a subprocess, against a mock API     |
+| Build      | `make build`     | The tsup bundle                                           |
+| Smoke      | `make smoke`     | Packs the tarball, installs it clean, and runs the binary |
-### Tech Stack
+**No test touches the network.** `tests/setup.ts` installs an MSW server with
+`onUnhandledRequest: 'error'`, so a request nobody mocked fails the test rather
+than quietly reaching a real Senso API with whatever key is in your environment.
+That is enforced mechanically, which is why CI needs no secrets and why pull
+requests from forks run the full suite.
-| Concern | Choice |
-|---------|--------|
-| Language | TypeScript |
-| Runtime | Node.js 18+ |
-| Bundler | tsup (esbuild) — single 50KB ESM bundle |
-| CLI Framework | Commander.js |
-| Interactive Prompts | @clack/prompts |
-| Colors | picocolors |
-| ASCII Branding | figlet + gradient-string + boxen |
-| Config | env-paths (XDG-compatible) |
-| HTTP | Native `fetch` |
+Run `make help` for every target.
-### Releasing a New Version
+## Repository layout
-This project uses [semantic versioning](https://semver.org/). The CLI's auto-update checker compares the installed version against the latest GitHub release using semver, so pre-release tags and version ordering are handled correctly.
-```bash
-# 1. Bump the version in package.json, commit, and create a git tag
-npm version patch   # 0.1.0 → 0.1.1 (bug fixes)
-npm version minor   # 0.1.0 → 0.2.0 (new features, backwards-compatible)
-npm version major   # 0.1.0 → 1.0.0 (breaking changes)
-# 2. Push the commit and tag
-git push origin main --tags
-# 3. Create a GitHub release (this is what the auto-updater checks)
-gh release create v0.2.0 --title "v0.2.0" --notes "Release notes here"
 ```
-After step 3, users running the CLI will see the update notice within 24 hours (or immediately via `senso update`).
----
+src/
+  cli.ts            The bin entry — the only file that ends the process
+  program.ts        createProgram(): builds the command tree, no side effects
+  commands/         One file per command group
+  lib/              api-client, config, errors, output, run-action
+  utils/            logger, branding, updater
+tests/
+  unit/             Library modules, in isolation
+  commands/         Each command group, in-process, against a mock API
+  e2e/              The built bundle, as a subprocess
+  policy/           This repository's own rules
+docs/               How it works, and the generated command reference
+scripts/            Reference generator, smoke test, pre-commit checks
+```
+## Documentation
+| Document                                                 | Read it when you want to know                                  |
+| -------------------------------------------------------- | -------------------------------------------------------------- |
+| [docs/README.md](docs/README.md)                         | How this CLI works, in 60 seconds and then in depth            |
+| [docs/reference/commands.md](docs/reference/commands.md) | Every command and flag                                         |
+| [docs/configuration.md](docs/configuration.md)           | Every environment variable and file it touches                 |
+| [docs/architecture.md](docs/architecture.md)             | What happens between argv and the API                          |
+| [docs/analytics.md](docs/analytics.md)                   | What every GEO metric divides by, and how to not misread one   |
+| [CONTRIBUTING.md](CONTRIBUTING.md)                       | How to make a change, and what a review will send back         |
+| [SECURITY.md](SECURITY.md)                               | What this tool holds, and what it does not do                  |
+| [CHANGELOG.md](CHANGELOG.md)                             | What changed and when                                          |
+| [CLAUDE.md](CLAUDE.md)                                   | Conventions, and the behaviors that look like bugs but are not |
 ## License
-[AGPL-3.0](LICENSE)
+[AGPL-3.0-or-later](LICENSE)