# Senso CLI

The Senso CLI manages your context layer from the terminal: ingest sources, run searches, generate content and publish it.

This page covers installing the CLI, signing in and the commands you use most. Every command
and flag is in the [full CLI reference](https://docs.senso.ai/docs/cli-reference).

## Installation

Requires Node.js 22.12 or later. Runs on Linux, macOS and Windows.

```bash
npm install -g @senso-ai/cli
```

## Sign in

```bash
senso login
```

`senso login` opens an approval page in your browser and prints a short code. Sign in, type
the code and approve. You must be an admin to approve. The CLI then stores your credentials
locally, so every command after that is signed in. The code works for five minutes.
Credentials last 7 days.

Running it again does nothing if your key still works, so an agent can safely run it at the
start of every session. Inside an agent, which cannot wait on a command, it prints the link
and code and exits. The agent then runs `senso login --complete`, which waits for your
approval and stores your credentials.

### Flags

- `--complete` — Finish a login started without a terminal: wait for the browser approval, then store your credentials.
- `--api-key <key>` — Store a key you already have instead of approving in a browser.
- `--interactive` — Paste an existing API key at a prompt instead. Needs a terminal.
- `--device-name <name>` — How this device is labeled on the approval page.
- `--no-browser` — Print the approval link without opening it.

- `senso logout` — revokes the key login created, then forgets it. Run logout and then login to switch organizations or renew early.
- `SENSO_API_KEY` — set it in the environment to use a key without storing it. It overrides the stored key, and senso whoami shows which one was used.

## Global flags

Available on every command. `--output json` prints structured output for scripts and agents,
and `--quiet` suppresses banners. The agent skills set both by default.

- `--api-key <key>` — use a specific key for one command
- `--output <json|table|plain>` — default is plain
- `--quiet` — hide banners and decoration
- `--no-update-check` — skip the version check

## Step 1 — Build the Context Layer

Get your approved sources in and query them.

- `senso ingest upload <files>` — Ingest up to 10 files at once.
- `senso kb upload <file> --folder-id <id>` — Ingest into a specific folder.
- `senso kb my-files` — List your sources and folders.
- `senso kb find --query "refund"` — Find a source by name.
- `senso kb create-folder --name "Policies"` — Create a folder.
- `senso brand-kit set --data '{…}'` — Set voice, tone and writing rules.
- `senso content-types create --data '{…}'` — Add an output template.
- `senso search "What is our refund policy?"` — Grounded answer with sources.
- `senso search context "mortgage rates"` — Raw chunks, no generated answer.

## Step 2 — Evaluate & Remediate

Track the questions that matter and fix what they expose.

- `senso prompts` — Manage the questions that drive generation.
- `senso questions` — Manage the questions monitored across models.
- `senso ingest reprocess <node-id> <file>` — Replace a source on an existing document.
- `senso content get <content-id>` — Read one compiled document.

## Step 3 — Generate & Verify

Draft against a gap, then check every claim in it.

- `senso generate sample --prompt-id <id> --content-type-id <id>` — Draft one piece.
- `senso generate run` — Trigger a full generation run.
- `senso content verification` — See what is waiting for review.
- `senso engine draft --data '{…}'` — Save a draft instead of publishing.

## Step 4 — Publish & Observe

- `senso engine publish --data '{…}'` — Publish verified content.

That is the only command in this step. Measurement lives on the REST API only, so read it with
[/org/analytics](https://docs.senso.ai/api-reference?tag=analytics) rather than looking for a `senso analytics`
that does not exist.

## Account and setup

- `senso whoami` — Check which organization your key resolves to.
- `senso org get` — Organization details.
- `senso credits balance` — What you have left.
- `senso api-keys list` — List keys.
- `senso setup` — Install the Senso agent skills.
- `senso update` — Update the CLI.

Run `senso --help` or `senso <command> --help` for full options.

## Limitations

- Ingest markdown by file. senso ingest upload rejects .md — send it as text with senso kb create-raw instead.
- Create an organization. senso org can get, update and set-runs, and nothing more.
- Publish on a brand-new organization. engine publish needs a tracked question id, and a fresh org has none.
- Report analytics. That is REST only.

**Supported upload formats:** PDF, TXT, CSV, DOC, DOCX, XLS, XLSX, PPT, PPTX, HTML, JSON and XML. Markdown and plain text go in as text, not as a file upload.

---

- [CLI Reference](https://docs.senso.ai/docs/cli-reference)
- [Connect Your Agent](https://docs.senso.ai/docs/connect-your-agent)
- [API Reference](https://docs.senso.ai/api-reference)