Skip to main content
The Gennia CLI (@gennia/cli) is the gennia command you run in your terminal. Three things it solves:
  1. gennia mcp install installs the MCP server 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.
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+.

​
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:
    CodeWhen
    0Success
    1Generic error or 5xx from the server
    2Usage error (bad flag, missing TTY for a prompt)
    3Not found (HTTP 404)
    4Unauthorized (HTTP 401/403, missing credential)
    5Conflict (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

VariableDefaultEffect
GENNIA_API_KEY—Workspace API key (gsk_...)
GENNIA_BASE_URLhttps://api.gennia.aiOverride for dev / local backend
GENNIA_CONFIG_DIR$XDG_CONFIG_HOME/gennia or ~/.config/genniaWhere config.json lives
NO_COLORunsetDisable 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.