> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gennia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> The gennia command. Auth, one-command MCP install, and a raw escape hatch into every Public API endpoint.

The **Gennia CLI** ([`@gennia/cli`](https://www.npmjs.com/package/@gennia/cli)) is the `gennia` command you run in your terminal. Three things it solves:

1. **`gennia mcp install`** installs the [MCP server](/en/api-reference/mcp) into every AI client on your machine (Cursor, Claude Code, Claude Desktop) in one go.
2. **`gennia api`** is the escape hatch into every Public API endpoint — useful for scripts, CI, bash automation.
3. **`gennia knowledge upload`**, `gennia skills upload`, `gennia hub upload-logo` cover what the MCP can't: multipart file uploads.

<Note>
  CLI and MCP **complement each other**. The MCP is for conversational chat inside your IDE / app; the CLI is for scripts, shell-bound agents, and bulk operations. Same API underneath, same `@gennia/sdk` internally.
</Note>

## Install

Requires **Node 20+**.

<Tabs>
  <Tab title="Global (recommended)">
    ```bash theme={null}
    npm install -g @gennia/cli
    gennia --version
    # 0.3.1
    ```
  </Tab>

  <Tab title="npx (no install)">
    ```bash theme={null}
    npx -y @gennia/cli@latest <command>
    ```

    Slower than the global version (downloads from npm on every call), but zero footprint on your machine.
  </Tab>
</Tabs>

## Authentication

```bash theme={null}
gennia auth login
```

Prompts for your API key (`gsk_...`) — you paste it, it shows as `********` while typing (raw-mode masking, doesn't leak into shell history). The credential is saved at `~/.config/gennia/config.json` with `0600` perms.

<Tip>
  **Default = production** (`api.gennia.ai`). If your key was generated in a dev/staging workspace, pass `--base-url`:

  ```bash theme={null}
  gennia auth login --base-url=https://api.dev.gennia.ai
  ```
</Tip>

Generate the key inside Studio: open your workspace, **Settings → API Keys**.

To confirm:

```bash theme={null}
gennia auth whoami

# Workspace:        86072856-d8e0-41ef-9462-66bafce30536
# API key ID:       ae48b1e6-cc58-4b76-a554-d02f8229cc73
# Base URL:         https://api.dev.gennia.ai
# Credential from:  config
```

Resolution order: `--api-key` flag → `GENNIA_API_KEY` env → config file.

## Install the MCP into your AI clients

```bash theme={null}
gennia mcp install
```

This is the **marquee command**. It auto-detects which AI clients you have installed (Claude Code, Cursor, Claude Desktop) and writes the MCP server config into the right file for each. It also drops a `SKILL.md` in Claude Code's skills directory so the agent "*knows*" about Gennia in fresh sessions.

Non-interactive flags for CI / scripts:

```bash theme={null}
gennia mcp install --target=claude-code,cursor --yes --json
gennia mcp install --dry-run                              # preview, don't write
gennia mcp install --update                               # overwrite an existing entry
gennia mcp install --no-skill                             # skip writing SKILL.md
```

Related commands:

```bash theme={null}
gennia mcp list      # show where gennia is installed and per-client status
gennia mcp status    # diagnostics: Node version, API reachable, npx on PATH, etc.
gennia mcp uninstall # remove from every client (or --target=<one>)
```

## Escape hatch: `gennia api`

Covers **every** Public API endpoint. The CLI doesn't need a custom wrapper for each — `gennia api METHOD /path` handles all of them.

```bash theme={null}
# List
gennia api GET /agents --limit 5

# Create
gennia api POST /agents --body '{"name":"Sales Bot","categories":["sales"]}'

# Body from file
gennia api POST /agents --body @./payload.json

# Body from stdin
echo '{"name":"Test"}' | gennia api POST /agents --body -

# Query params
gennia api GET /agents --query 'limit=20&status=active'

# Auto-paginate (walks items[] until exhausted)
gennia api GET /agents --all > agents.json

# Pipe into jq
gennia api GET /agents --all | jq -r '.items[].publicId' | while read id; do
  gennia api PATCH /agents/$id --body '{"categories":["sales"]}'
done
```

Paths can be:

* Relative: `/agents` → resolves to `https://api.gennia.ai/public/api/v1/agents`
* Absolute with prefix: `/public/api/v1/agents`
* Full URL: `https://api.dev.gennia.ai/public/api/v1/agents`

## File uploads

Three API endpoints take `multipart/form-data` instead of JSON. The CLI has dedicated commands:

```bash theme={null}
# Knowledge source (PDF, TXT, CSV, DOCX, MD)
gennia knowledge upload ./manual.pdf --name "Q4 2026 Manual"
gennia knowledge upload ./data.csv --metadata '{"name":"Sales 2026","description":"raw export"}'

# Skill bundle (ZIP, .skill, or standalone SKILL.md)
gennia skills upload ./my-skill.zip

# Hub logo
gennia hub upload-logo ./logo.png --type=horizontal   # or icon | email | banner
```

All support `--json` and the standard exit codes (see below).

## Output contract

Every CLI command follows the same rules so it's reliable in scripts and safe for AI agents:

* **stdout = data.** Stable JSON by default in non-TTY, pretty in TTY. Force JSON with `--json`.

* **stderr = humans.** Banners, progress, hints. Suppress with `--quiet`.

* **`NO_COLOR=1`** disables ANSI colors on any command.

* **Exit codes** that mean something:

  | Code | When                                             |
  | ---- | ------------------------------------------------ |
  | 0    | Success                                          |
  | 1    | Generic error or 5xx from the server             |
  | 2    | Usage error (bad flag, missing TTY for a prompt) |
  | 3    | Not found (HTTP 404)                             |
  | 4    | Unauthorized (HTTP 401/403, missing credential)  |
  | 5    | Conflict (HTTP 409, existing configuration)      |

* **Errors are always structured.** In `--json` mode:

  ```json theme={null}
  {
    "error": {
      "code": "config_conflict",
      "message": "An existing MCP entry differs from what would be installed.",
      "hint": "Re-run with --update to overwrite, or `gennia mcp uninstall` first."
    }
  }
  ```

* **No interactive hang.** Every command that needs input detects non-TTY and fails fast with a hint pointing at the missing flag.

## Environment

| Variable            | Default                                         | Effect                           |
| ------------------- | ----------------------------------------------- | -------------------------------- |
| `GENNIA_API_KEY`    | —                                               | Workspace API key (`gsk_...`)    |
| `GENNIA_BASE_URL`   | `https://api.gennia.ai`                         | Override for dev / local backend |
| `GENNIA_CONFIG_DIR` | `$XDG_CONFIG_HOME/gennia` or `~/.config/gennia` | Where `config.json` lives        |
| `NO_COLOR`          | unset                                           | Disable ANSI colors              |

## Bundled skill file

Every CLI install ships a **`skill.md`** (\~6 KB) that `gennia mcp install` copies into `~/.claude/skills/gennia/SKILL.md` (and the Cursor equivalent). It's a markdown file that teaches the AI agent:

* When to reach for MCP tools vs `gennia api` in the shell
* Domain → endpoint mapping
* Common workflows (list every agent, bulk update, etc.)
* Caveats (uploads need `file_path`, destructive mutations ask for confirmation)

Net effect: the first session of any AI client on your machine already "*knows*" about Gennia, without you having to explain.

## Update

```bash theme={null}
npm install -g @gennia/cli@latest
gennia --version
```

Or see [GitHub releases](https://github.com/Gennia-Tech-Group/gennia-cli/releases). Packages are signed with [SLSA provenance](https://slsa.dev) (the "Built and signed on GitHub Actions" badge on npm).

## Source

[github.com/Gennia-Tech-Group/gennia-cli](https://github.com/Gennia-Tech-Group/gennia-cli) — MIT, public.

## Next steps

<CardGroup cols={2}>
  <Card title="Install the MCP" icon="plug" href="/en/api-reference/mcp">
    The CLI already installs the MCP via `gennia mcp install`, but it's worth reading how the MCP server works and what you gain from it.
  </Card>

  <Card title="Full reference" icon="book" href="/en/api-reference/introduction">
    Every endpoint that `gennia api` calls is documented here with schemas and try-it-out.
  </Card>
</CardGroup>