CLI

The Gennia CLI (@gennia/cli) is the gennia command you run in your terminal. Three things it solves:

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

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.

Install

Requires Node 20+.

Global (recommended)
npx (no install)

npm install -g @gennia/cli
gennia --version
# 0.3.1

npx -y @gennia/cli@latest <command>

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

Authentication

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.

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

gennia auth login --base-url=https://api.dev.gennia.ai

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

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

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:

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:

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.

# 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:

# 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:

{
  "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

npm install -g @gennia/cli@latest
gennia --version

Or see GitHub releases. Packages are signed with SLSA provenance (the “Built and signed on GitHub Actions” badge on npm).

Source

github.com/Gennia-Tech-Group/gennia-cli — MIT, public.

Next steps

Install the 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.

Full reference

Every endpoint that gennia api calls is documented here with schemas and try-it-out.

Getting started

Conventions

Agents

Threads

Hub

Install

Authentication

Install the MCP into your AI clients

Escape hatch: `gennia api`

File uploads

Output contract

Environment

Bundled skill file

Update

Source

Next steps

Install the MCP

Full reference

​Install

​Authentication

​Install the MCP into your AI clients

​Escape hatch: gennia api

​File uploads

​Output contract

​Environment

​Bundled skill file

​Update

​Source

​Next steps

Install the MCP

Full reference

Install

Authentication

Install the MCP into your AI clients

Escape hatch: `gennia api`

File uploads

Output contract

Environment

Bundled skill file

Update

Source

Next steps