Agent Integration

Drive Contento from AI coding agents. Non-interactive auth, structured output, and streaming.

Overview

The Contento CLI is designed to be operated by both humans and AI agents. Every command supports a --json flag that outputs structured JSON instead of formatted tables, making it trivial for agents to parse responses, make decisions, and chain commands together.

Supported agents include:

• Claude Code — Anthropic's CLI agent for coding tasks
• Codex — OpenAI's coding agent
• Cursor / Windsurf — IDE-based AI coding tools
• Custom agents — Any tool that can execute shell commands and parse JSON

Non-Interactive Authentication

Agents cannot complete interactive prompts. Configure the AI provider key once via environment variables — the CLI reads them automatically with no further setup:

# Set the provider key in the agent's environment
$ export OPENAI_API_KEY=sk-proj-...
# or ANTHROPIC_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY

# Confirm the active configuration
$ contento config show --json
{"provider":"openai","model":"gpt-4o-mini","enabled":true}

# Override per-run if the agent wants a different model
$ contento collections generate col_9d2f... --provider anthropic --model "claude-3-5-haiku" --json

Contento has no central server — the only credentials it ever holds are the AI provider keys you configure. Set them per-shell, in your CI secret store, or in the agent's environment.

JSON Output Mode

Every command supports --json for structured output. This is the mode agents should always use.

List commands return arrays

$ contento projects list --json

[
  {
    "id": "proj_8f3a...",
    "name": "DevTools Resources",
    "outputPath": "./dist/resources",
    "status": "active",
    "pageCount": 248
  }
]

Show commands return objects

$ contento niches view niche_01... --json

{
  "id": "niche_01...",
  "name": "Developer Tools",
  "category": "Software / SaaS",
  "subtopics": ["CI/CD pipelines", "API testing tools", "..."],
  "audience": "Software developers and DevOps engineers"
}

Action commands return result objects

$ contento publish col_9d2f... --mode immediate --json

{
  "batchId": "batch_1a3c...",
  "pagesPublished": 48,
  "crossLinksAdded": 142,
  "sitemapUrls": 48
}

NDJSON Streaming for Generation

The collections generate command with --json outputs newline-delimited JSON (NDJSON) for real-time progress tracking. Each line is a complete JSON object:

$ contento collections generate col_9d2f... --json

{"type":"progress","current":0,"total":40,"done":false}
{"type":"page","id":"page_01...","status":"passed","title":"100 CI/CD Ideas"}
{"type":"page","id":"page_02...","status":"retried","title":"50 API Testing Ideas"}
{"type":"progress","current":20,"total":40,"done":false}
{"type":"progress","current":40,"total":40,"done":true}
{"type":"done","passed":38,"retried":2,"failed":0}

Event Types

Type	Fields	Description
progress	current, total, done	Overall job progress
page	id, status, title	Individual page result (passed, retried, failed)
done	passed, retried, failed	Final tallies when generation completes
error	message	Fatal error that stopped the job

Agent Workflow Examples

Full pSEO Pipeline

An agent can execute the entire pSEO workflow as a sequence of CLI commands:

# 1. Initialize project
$ contento init \
    --name "DevTools Resources" \
    --json

# 2. List available niches and schemas
$ contento niches list --category "Software / SaaS" --json
$ contento schemas list --json

# 3. Generate pages
$ contento collections generate col_9d2f... --json

# 4. Publish
$ contento publish col_9d2f... \
    --mode immediate \
    --json

# 5. Check analytics (after 30+ days)
$ contento analytics summary proj_8f3a... --json
$ contento analytics top-pages proj_8f3a... --json
$ contento analytics zero-traffic proj_8f3a... --json

Optimization Loop

Agents can implement an automated optimization cycle:

# 1. Check which niches perform best
$ contento analytics summary proj_8f3a... --json

# 2. Find underperforming pages
$ contento analytics zero-traffic proj_8f3a... --json

# 3. Create and generate new collection with different schema
$ contento collections create --project proj_8f3a... --schema faq --niches niche_01... --json
$ contento collections generate col_new... --json

# 4. Publish the new batch
$ contento publish col_new... --mode batched --batch-size 25 --json

MCP Tool-Use Pattern

Contento ships with built-in MCP server support — run contento mcp serve to expose every command as a typed tool to any MCP-compatible agent (Claude Code, Codex, Cursor). Each CLI command becomes a tool; each flag becomes a typed parameter:

// MCP tool definition (conceptual)
{
  "name": "contento_collections_generate",
  "description": "Generate pSEO pages for a project",
  "parameters": {
    "project": { "type": "string", "required": true },
    "schema": { "type": "string", "required": true },
    "niches": { "type": "string", "required": true },
    "workers": { "type": "number", "default": 5 }
  }
}

The agent translates this into:

$ contento collections create --project proj_8f3a... --schema idea-list --niches niche_01...,niche_02... --json
$ contento collections generate col_9d2f... --json

Error Handling

When a command fails, the CLI exits with a non-zero code and outputs a JSON error object (when --json is used):

$ contento projects status proj_invalid... --json
{"error":"NOT_FOUND","message":"Project not found: proj_invalid..."}
# Exit code: 1

Exit Code	Meaning
0	Success
1	General error (check JSON error output)
2	Invalid arguments or missing required flags
3	Authentication failure (invalid or expired key)

Best Practices for Agents

• Always use --json — Human-formatted tables are not parseable. JSON output is stable and versioned.
• Set the provider env var — e.g., OPENAI_API_KEY or ANTHROPIC_API_KEY. Never attempt interactive prompts from an agent context.
• Check exit codes — A zero exit code means success. Non-zero means the command failed.
• Parse NDJSON line by line — Generation output is streamed. Process each line as an independent JSON object.
• Wait before analytics — GSC data takes 2-4 weeks to populate for new pages. Do not evaluate performance before 30 days.
• Use batched publishing — Agents should prefer --mode batched over --mode immediate for large collections to monitor indexing.