Docs CLI Reference

CLI Reference

Every command, flag, and configuration option for the Contento CLI.

Installation

$ npm install -g contento-cli
$ contento --version
  contento/0.1.0

Requires Node.js 18+ and npm 9+. See Install CLI for detailed setup.

Global Flags

Flag	Description
`--json`	Output as JSON (machine-readable). Required for agent integration.
`--no-color`	Disable colored output
`-v, --verbose`	Show detailed request/response logging
`-V, --version`	Print version number
`-h, --help`	Show help for any command

No login. Contento has no central account or authentication system. The CLI runs entirely on your machine. The only credentials it ever holds are the AI provider keys you configure with contento config set (see AI Configuration below) and, optionally, a Google OAuth token for GSC analytics.

Projects

contento projects list

List all projects discoverable from the current directory (any directory containing a contento.config.json).

$ contento projects list

  ID            Name                 Output Path                Status   Pages
  proj_8f3a...  DevTools Resources   ./dist/articles            active   248
  proj_2b1c...  Marketing Blog       ./dist/blog                active   120

contento projects create

Create a new pSEO project.

Flag	Description
`--name <name>`	Project name (required)

$ contento init \
    --name "DevTools Resources"

  ✓ Project created
  Project "DevTools Resources" created with ID: proj_8f3a...

  ID       proj_8f3a...
  Name     DevTools Resources
  Status   active

contento projects status <id>

Show detailed project status including page counts and build info.

$ contento projects status proj_8f3a...

contento projects chrome <id>

Upload custom chrome (header, footer, CSS) from files or inline. Takes a project ID as the first argument.

Flag	Description
`--header <file>`	Path to header HTML file
`--footer <file>`	Path to footer HTML file
`--css <file>`	Path to custom CSS file
`--header-html <html>`	Inline header HTML string
`--footer-html <html>`	Inline footer HTML string
`--css-inline <css>`	Inline CSS string

$ contento projects chrome proj_8f3a... \
    --header chrome/header.html \
    --footer chrome/footer.html \
    --css chrome/styles.css

  ✓ Chrome updated
  Project chrome updated successfully.

Init

contento init

Top-level alias for contento projects create. Initializes a new project in the current directory and writes contento.config.json.

Flag	Description
`--name <name>`	Project name (required)

$ contento init \
    --name "DevTools Resources"

  ✓ Project created
  Project "DevTools Resources" created with ID: proj_8f3a...

  ID       proj_8f3a...
  Name     DevTools Resources
  Status   active

Build

contento build <project-id>

Render published pages to static HTML files locally. Applies your chrome, runs the internal linking pass, and writes a sitemap into the output directory.

Flag	Description
`--output <dir>`	Output directory for static HTML files (required)
`--flat`	Write files as `slug.html` instead of `slug/index.html`

$ contento build proj_8f3a... --output ./dist

  ✓ Built 48 pages to ./dist/
  HTML files:  48
  Sitemap:     ./dist/sitemap.xml

  Deploy with your existing pipeline: git push, netlify deploy, rsync, etc.

Niches

contento niches list

List available niches. Filter by category.

$ contento niches list --category "Software / SaaS"

  Slug                  Name                  Category          Subtopics
  developer-tools       Developer Tools       Software / SaaS   20
  project-management    Project Management    Software / SaaS   20
  crm                   CRM                   Software / SaaS   20

contento niches view <id>

View detailed information about a niche (audience, pain points, subtopics).

$ contento niches view niche_01... --json

contento niches fork <id>

Create a custom copy of a system niche for editing.

$ contento niches fork niche_01... --name "Custom DevTools"

  ✓ Forked "Developer Tools" as "Custom DevTools" (niche_4f2a...)
  Edit subtopics and context at: contento niches edit niche_4f2a...

Schemas

contento schemas list

List all available content schemas.

$ contento schemas list

  Slug             Name              Title Pattern
  idea-list        Idea List         {count} {subtopic} Ideas for {year}
  comparison       Comparison        {subtopic} vs Alternatives: Comparison
  how-to           How-To Guide      How to {subtopic}: Complete Guide
  best-of          Best-Of List      Best {subtopic} Tools & Resources
  faq              FAQ               {subtopic} FAQ: Common Questions

Collections

contento collections list

List collections for a project.

$ contento collections list --project proj_8f3a...

contento collections generate <id>

Start AI generation for a collection. Takes the collection ID as an argument. Streams real-time progress by default.

Flag	Description
`--workers <n>`	Number of concurrent AI workers (default: 5)
`--json`	Output NDJSON progress stream (for agent consumption)

$ contento collections generate col_9d2f...

  ✓ Generation started (Job: job_4a1b...)
  [00:26] ████████████████████ 40/40 (100%)
  ✓ Generation complete!

With --json, the same run streams as newline-delimited JSON events that an agent can pipe and parse:

$ contento collections generate col_9d2f... --json

{"type":"progress","current":0,"total":40,"done":0}
{"type":"page","id":"page_a1...","status":"validated","title":"..."}
{"type":"progress","current":1,"total":40,"done":1}
{"type":"done","passed":40,"retried":2,"failed":0}

Publishing

contento publish <collection-id>

Publish a collection. Takes the collection ID as the first argument.

Flag	Description
`--mode <mode>`	`immediate`, `batched`, `scheduled`, or `manual`. Default: `immediate`
`--batch-size <n>`	Pages per batch (for batched mode). Default: 50

$ contento publish col_9d2f... --mode immediate

  ✓ Publish initiated
  Published all pages immediately.

Analytics

contento analytics summary <project-id>

Project-level analytics summary (clicks, impressions, CTR, position).

Flag	Description
`--days <n>`	Number of days to look back. Default: 30

$ contento analytics summary proj_8f3a...

contento analytics top-pages <project-id>

Top pages ranked by performance.

Flag	Description
`--days <n>`	Number of days to look back. Default: 30
`--limit <n>`	Number of pages to show. Default: 20

$ contento analytics top-pages proj_8f3a... --limit 10

contento analytics zero-traffic <project-id>

Pages with zero traffic.

Flag	Description
`--days <n>`	Minimum age in days before flagging. Default: 14

$ contento analytics zero-traffic proj_8f3a...

contento analytics export <project-id>

Export analytics data as CSV.

Flag	Description
`--format <fmt>`	Export format. Default: `csv`
`--days <n>`	Number of days to look back. Default: 30

$ contento analytics export proj_8f3a...

contento analytics connect <project-id>

Run the GSC OAuth flow in your default browser and store the refresh token locally. One-time setup per project.

contento analytics sync <project-id>

Pull the last 28 days of GSC data into the local SQLite cache at ~/.contento/analytics.db. Schedule via cron for a daily refresh.

AI Configuration (BYOK)

Contento uses Bring Your Own Key (BYOK) — you provide your own AI provider API key for content generation. Configure it once before running your first generation.

contento config show

Display your current AI provider, model, and key status.

$ contento config show

  Provider:  openai
  Model:     openai/gpt-4o-mini
  Enabled:   yes
  API Key:   sk-proj-A...xkN9

contento config set

Set or update your AI provider, model, and API key. Run without flags for interactive mode.

Flag	Description
`--provider <provider>`	AI provider: `openai`, `anthropic`, `groq`, `openrouter`, `ollama`, or `custom` (all non-anthropic options use the OpenAI-compatible API; pair with `--base-url` for groq/openrouter/ollama/custom)
`--model <model>`	Model identifier (e.g., `openai/gpt-4o-mini`, `anthropic/claude-sonnet-4-20250514`)
`--api-key <key>`	Your AI provider API key

Interactive mode (recommended for first-time setup):

$ contento config set

  Configure your AI provider for content generation (BYOK).

  ? AI Provider: OpenAI
  ? Model: GPT-4o Mini (default)
  ? API Key: ************************************

  ✓ AI configuration updated
  Provider:  openai
  Model:     openai/gpt-4o-mini
  API Key:   sk-proj-A...xkN9
  Enabled:   yes

Non-interactive mode (for CI/CD and scripts):

$ contento config set \
    --provider openai \
    --model "openai/gpt-4o-mini" \
    --api-key "sk-proj-your-key-here"

Supported Providers & Models

Provider	Model	Identifier
OpenAI	GPT-4o	`openai/gpt-4o`
OpenAI	GPT-4o Mini (default)	`openai/gpt-4o-mini`
OpenAI	GPT-4.1	`openai/gpt-4.1`
OpenAI	GPT-4.1 Mini	`openai/gpt-4.1-mini`
OpenAI	GPT-4.1 Nano	`openai/gpt-4.1-nano`
Anthropic	Claude Sonnet 4	`anthropic/claude-sonnet-4-20250514`
Anthropic	Claude Haiku 3.5	`anthropic/claude-3-5-haiku-20241022`

contento config clear

Remove your AI API key and disable content generation.

$ contento config clear

  ✓ AI configuration cleared

Configuration Files

Contento stores everything in ~/.contento/ on your machine:

Path	Contents
`~/.contento/config.json`	AI provider, model, and key
`~/.contento/niches/`	Custom and forked niches as JSON files
`~/.contento/projects/`	Generated content cache per project
`~/.contento/analytics.db`	SQLite cache of GSC data
`~/.contento/gsc.json`	Google OAuth refresh token (per project)
`~/.contento/logs/`	Per-run generation logs

Each project also has a contento.config.json in its working directory containing the project ID, domain, output path, and chrome file paths. Commit it to git so your team uses the same configuration.

Environment Variables

AI provider keys can be supplied via environment variables instead of contento config set — useful in CI and agent environments:

Variable	Description
`OPENAI_API_KEY`	OpenAI API key (used when provider is `openai`)
`ANTHROPIC_API_KEY`	Anthropic API key
`GROQ_API_KEY`	Groq API key
`OPENROUTER_API_KEY`	OpenRouter key
`CONTENTO_PROVIDER`	Override the configured provider (e.g., `openai`, `anthropic`)
`CONTENTO_MODEL`	Override the configured model identifier
`NO_COLOR`	Disable colored output (standard convention)

Precedence: environment variables > config file > defaults.

Command Summary

Command	Description
`contento init`	Create a new project in the current directory
`contento config show`	Show AI provider configuration
`contento config set`	Configure AI provider, model, and key (BYOK)
`contento config clear`	Remove the AI key and disable generation
`contento projects list`	List all projects in the current workspace
`contento projects status`	Show project status
`contento projects chrome`	Configure chrome (header, footer, CSS) paths
`contento niches list`	List built-in and custom niches
`contento niches view`	View niche details
`contento niches fork`	Fork a system niche for editing
`contento niches create`	Create a custom niche from scratch
`contento niches edit`	Edit a custom niche (subtopics, audience, context)
`contento schemas list`	List content schemas
`contento collections list`	List collections in a project
`contento collections create`	Create a new collection
`contento collections generate`	Generate content for a collection
`contento publish`	Publish a collection (immediate, batched, manual; `scheduled` is reserved for cron-driven workflows)
`contento build`	Render published pages to static HTML
`contento analytics connect`	OAuth Google Search Console for a project
`contento analytics sync`	Pull GSC data into the local cache
`contento analytics summary`	Project analytics overview
`contento analytics top-pages`	Top performing pages
`contento analytics zero-traffic`	Underperforming pages
`contento analytics export`	Export analytics as CSV