| name | ideon-cli |
| description | Use this skill when users need to install, configure, run, automate, preview, and troubleshoot the Ideon CLI from zero context. Covers non-interactive write/resume/plan/queue/export workflows, GKP research, publications/series management, and starting the MCP server. Do not use for quick single-flag explanations or MCP tool schemas (use ideon-mcp skill). |
Ideon CLI Skill
Operate Ideon as a content writer platform from the terminal: one idea to multi-channel outputs (article, blog, newsletter, social, etc.), optional link enrichment and images, resume/checkpoint support, and export. For MCP tool workflows inside clients, use the ideon-mcp skill.
Agent constraints
- Always pass
--no-interactive on write, resume, queue, and plan commands — without it, commands hang waiting for stdin.
- Never invoke
ideon settings — requires interactive user input.
- Telepat Monad / MCP contexts: use MCP
gads_login / gads_login_status / gads_test — never SSH ideon gads login. After OAuth, persist refreshToken as TELEPAT_GOOGLE_ADS_REFRESH_TOKEN in .env when saved: false.
- Bare-metal desktop:
ideon gads login is fine for interactive OAuth; agents without MCP should not call it non-interactively.
- Use MCP
ideon_preview with port: 5679 in Monad; give users TELEPAT_IDEON_PREVIEW_URL, not internal localhost URLs.
- Always use
--force on ideon delete and ideon queue remove/clear after explicit user confirmation.
- Run dry-run or read-only commands before full generation.
- In containers/CI: set
TELEPAT_DISABLE_KEYTAR=true and inject secrets via env vars.
Installation
Prerequisites: Node.js 20+, npm 10+, OpenRouter API key, Replicate API token.
npm i -g @telepat/ideon
ideon --help
ideon --version
Setup and readiness
Non-interactive setup (agents, CI, containers):
TELEPAT_DISABLE_KEYTAR=true \
TELEPAT_OPENROUTER_KEY=sk-... \
TELEPAT_REPLICATE_TOKEN=r8_... \
ideon config list --json
Readiness checklist:
- CLI responds:
ideon --help
- Config readable:
ideon config list --json
- Pipeline works:
ideon write --dry-run "Smoke test" --primary article=1 --style professional --intent tutorial --length medium --no-interactive
- Preview starts:
ideon preview --no-open (expect Open http://localhost:<port>)
Human users may run ideon settings for an interactive wizard.
Agent host integration
Install Ideon into supported coding-agent hosts (skills + optional MCP):
ideon agent install pi
ideon agent install cursor --mcp-skill
ideon agent install claude --project
ideon agent status --json
Supported runtimes: pi, claude, claude-desktop, chatgpt, gemini, codex, cursor, vscode, opencode, hermes, generic-mcp. Default mode installs ideon-cli; --mcp-skill is mutually exclusive and registers stdio MCP (ideon mcp serve). Use --force to replace conflicting Ideon-managed entries only.
Inputs to collect from user
Always collect all relevant inputs before running any command. Ask the user for the values needed based on the operation they want.
Write / resume
| Input | Required | Why it matters |
|---|
| Idea text | Yes | Required by ideon write unless a job file provides it. |
Primary target (--primary) | Yes | Must be exactly one primary with count 1. |
Secondary targets (--secondary) | No | Optional channel variants and counts. |
Style (--style) | Yes | Required for non-interactive runs when not supplied via job. |
Intent (--intent) | Yes | Required for non-interactive runs when not supplied explicitly. |
Length (--length) | Yes | Required for non-interactive runs when not supplied via job. small / medium / large. |
Publication (--publication) | No | Publication slug for defaults and editorial policy. |
Series (--series) | No | Content series slug for defaults and thematic context. |
Author (--author) | No | Author slug for voice and expertise. Overrides publication/series default authors. |
Experience (--experience) | No | Per-run anecdotes or first-hand experience to weave into the draft. |
Keywords (--keywords) | No | Comma-separated SEO keywords. Supports compound keywords. Merges with series keywords. |
FAQ section (--faq-section / --no-faq-section) | No | Force FAQ block on or off after conclusion (overrides intent default). |
Export path (--export) | No (write/resume) | Export generated article to directory after write completes. |
Audience (--audience) | No | Target audience description injected into editorial policy. |
Enrich links (--enrich-links) | No | Opt-in web research link enrichment for long-form outputs. |
Max links (--max-links) | No | Cap generated links (defaults: ≤700w→5, ≤1150w→8, >1150w→12). |
Max images (--max-images) | No | Cap total images (1=cover only, higher=cover+inline). |
Skip SEO check (--no-seo-check) | No | Skip post-section SEO lint and editor pass on ideon write. |
SEO check mode (--seo-check-mode) | No | errors-only (default) or strict (zero warnings). |
SEO check max turns (--seo-check-max-turns) | No | Max editor-agent turns during SEO check (1–20, default 10). |
Force SEO re-check (--seo-check) | No (resume) | Re-run SEO lint and editor on ideon write resume. |
| Credentials strategy | Yes | Env-based secrets for CI/agents (TELEPAT_OPENROUTER_KEY, TELEPAT_REPLICATE_TOKEN). |
| Run mode | Yes | Fresh run vs ideon write resume vs ideon write --from-queue. |
Plan explore / expand
| Input | Required | Why it matters |
|---|
| Content idea | Yes (explore) | The topic to research. |
| Series slug | Yes (expand) | The existing series to expand. |
Publication (--publication) | Yes | Publication slug. Must exist. |
Context (--context) | No (explore) | Business context or ICP description for better LLM results. |
Series count (--series-count) | No (explore) | Number of series to aim for (default 3). |
Articles per series (--articles-per-series) | No (explore) | Articles per series (default 5). |
Article count (--article-count) | No (expand) | New articles to plan (default 5). |
Seed keywords (--seed-keywords) | No | Comma-separated keywords to always include in research. |
Exclude series (--exclude-series) | No (explore) | Series slugs to avoid duplicating. |
Country (--country) | No | Comma-separated ISO codes for GKP queries (defaults from publication). |
Language (--language) | No | ISO 639-1 code for GKP queries (defaults from publication). |
Content type (--content-type) | No | Content type for queue entries (default article). |
Model (--model) | No | LLM model for reasoning calls (default deepseek/deepseek-v4-pro). |
Intent model (--intent-model) | No | LLM model for intent classification (default deepseek/deepseek-v4-flash). |
Dry run (--dry-run) | No | Run research without persisting. |
GKP research
| Input | Required | Why it matters |
|---|
Keywords (--keywords) | Yes (except ideas) | Comma-separated keywords to query. |
URL (--url) | No (ideas only) | URL to generate keyword ideas from. |
Site (--site) | No (ideas only) | Site domain to generate keyword ideas from. |
Country (--country) | No | ISO country code for geography-specific volume (default US). |
Language (--language) | No | ISO 639-1 language code (default en). |
Match type (--match-type) | No (forecast) | EXACT, PHRASE, or BROAD. |
Max CPC bid (--max-cpc-bid) | No (forecast) | Max CPC bid in micros for forecast projections. |
Start date (--start-date) | No (forecast) | Forecast start date (YYYY-MM-DD). |
End date (--end-date) | No (forecast) | Forecast end date (YYYY-MM-DD). |
Include CPC (--no-include-cpc) | No (historical) | Omit CPC data from historical results. |
Page size (--page-size) | No (ideas) | Number of results per page. |
Publication (cache) (--publication) | No | Attach cache context to a publication slug. |
Series (cache) (--series) | No | Attach cache context to a series slug. |
Refresh cache (--refresh) | No | Bypass cache and fetch fresh data. |
GKP cache list
| Input | Required | Why it matters |
|---|
Publication (--publication) | No | Filter by publication slug. |
Series (--series) | No | Filter by series slug. |
Search (--search) | No | Filter by keyword, URL, site, publication, or series text. |
Fresh only (--fresh) | No | Show only fresh cache entries. |
Stale only (--stale) | No | Show only stale cache entries. |
Verbose (--verbose) | No | Include full cache entry details. |
Queue
| Input | Required | Why it matters |
|---|
| Idea text | Yes | Article idea to enqueue. |
Primary target (--primary) | No | Defaults to article=1. |
Secondary targets (--secondary) | No | Optional channel variants. |
Publication (--publication) | No | Publication slug. |
Series (--series) | No | Series slug. |
Style (--style) | No | Writing style. |
Intent (--intent) | No | Content intent. |
Length (--length) | No | Target word count alias (small/medium/large). |
Keywords (--keywords) | No | Comma-separated SEO keywords. |
Audience (--audience) | No | Target audience description. |
Other commands
| Command | Required inputs |
|---|
ideon links <slug> | slug (required), --mode (fresh/append, optional), --link (optional, repeatable), --unlink (optional, repeatable), --max-links (optional) |
ideon export <genId> <path> | generationId (required), path (required), --index (optional, default 1), --overwrite (optional) |
ideon delete <slug> | slug (required), must ask user for confirmation, then use --force |
ideon preview | --port (optional, default 4173), --no-open (always use for agents), --watch (optional) |
Deterministic workflow
- Discover the user's intent — what operation do they need (write, plan, query GKP, queue, links, export, delete, preview)?
- Collect all required inputs from the Inputs to collect tables. Do not guess missing values.
- Confirm install and setup state using the readiness checklist.
- Choose operation path:
- Create content:
ideon write ...
- Resume interrupted run:
ideon write resume
- Plan content series and articles:
ideon plan explore / ideon plan expand
- Queue articles:
ideon queue add ... → ideon write --from-queue
- Enrich links:
ideon links <slug>
- List/search articles:
ideon article list
- Export:
ideon export <generationId> <path>
- Preview:
ideon preview ...
- Delete:
ideon delete <slug> --force
- Config:
ideon config ...
- MCP server:
ideon mcp serve or ideon mcp serve-http
- Run minimal safe command first (dry-run or read-only status).
- Escalate to full workflow only after verification succeeds.
- Report: command run, artifacts/paths touched, exit/result, next safe step.
After a successful write
- List or locate the generation:
ideon article list or ideon article list --json.
- Read
<generationDir>/meta.json for title, slug, all outputs[], images, editorialChecklist, and seoCheck.
- Open primary markdown (usually
article-1.md in that directory).
- Preview with
ideon preview --no-open if the user wants a browser view.
- Export with
ideon export <slug> <dest-dir> when publish-ready markdown with inlined links is needed.
Full artifact schemas and directory layout: references/output-structure.md.
Canonical examples
Write
ideon write "Your idea" \
--primary article=1 \
--style technical \
--intent tutorial \
--length medium \
--no-interactive
With publication, series, and link enrichment:
ideon write "Your idea" \
--primary article=1 \
--publication tech-blog \
--series ai-deep-dives \
--enrich-links \
--no-interactive
Resume
ideon write resume --no-interactive
ideon write resume --no-interactive --export ./out
Queue write
ideon queue add "Your idea" --primary article=1 --style technical --intent tutorial --no-interactive
ideon write --from-queue --no-interactive
ideon write --from-queue --publication tech-blog --no-interactive
Plan
ideon plan explore "Your content idea" --publication my-blog --non-interactive
ideon plan expand my-series --publication my-blog --non-interactive
ideon plan explore "Your content idea" --publication my-blog --non-interactive --auto-save
Export and links
ideon export my-article-slug ./export-dir
ideon export my-article-slug ./export-dir --overwrite
ideon links my-article-slug
ideon links my-article-slug --mode append --max-links 5
Preview
ideon preview --no-open
ideon preview --watch --no-open
Read stdout for Open http://localhost:<port> and share the URL with the user.
For publication, series, author, queue CRUD, and additional write flags, see references/command-catalog.md (command matrix and scenario paths).
MCP server
Start the first-party MCP server from the CLI. For tool schemas, JSON examples, and MCP-specific gotchas, use the ideon-mcp skill.
ideon mcp serve
ideon mcp serve-http --api-key <key> [--port <port>] [--host <host>] [--endpoint <path>]
HTTP defaults: 127.0.0.1:3001, endpoint /mcp. API key via --api-key or IDEON_MCP_API_KEY.
Google Keyword Planner (CLI)
GKP commands require six Google Ads credentials. Set via ideon config set or env vars — see references/google-ads-setup.md.
ideon gads status
ideon gads test
ideon gads logout
ideon gads logout --all
ideon gkp ideas --keywords seo,marketing --country US --language en
ideon gkp historical --keywords seo --country US --json
ideon gkp forecast --keywords seo --match-type EXACT --country US --json
ideon gkp list --publication tech-blog --search "content strategy" --fresh
All gkp subcommands support --publication, --series, and --refresh for cache context. Credential errors include setup instructions in the error message.
Publications, series, and queue
Settings resolution: saved settings → job file → env vars → publication defaults → series defaults → CLI flags.
When a publication or series is active, editorial policy (tone, forbidden topics, disclosures, audience restrictions, notes) is injected into all LLM prompts.
Queue lifecycle: enqueue snapshots settings → claim via --from-queue (atomic rename) → success deletes entry, failure reverts to pending. --export paths stored at enqueue time are used at write time.
See references/command-catalog.md for ideon publication *, ideon series *, ideon author *, and ideon queue * commands.
Content planning
Agents must always use --non-interactive. Without it, the command opens an interactive TUI and hangs.
After research completes, ask the user whether to auto-save. If they decline, present the plan output and ask for confirmation before saving.
Pipeline stages: hydrate → seeds → research → score → cluster (explore only) → plan-articles → persist
| Flag | Effect |
|---|
--non-interactive | Required for agents. Skips TUI; writes plan to stdout |
--auto-save | Persists without human confirmation — only after user agrees |
--dry-run | Research only, writes nothing |
Exit codes: 0 = persisted, 1 = pipeline error, 2 = no results (topic exhausted).
Full explore/expand options: references/command-catalog.md.
Argument semantics and constraints
Target specs: format <content-type=count>. Primary count must be 1. Same type cannot be both primary and secondary.
Allowed values for content types, styles, intents, and lengths: see references/command-catalog.md § Argument and option semantics.
Key constraints:
- Agents must always use
--no-interactive — missing required inputs fail fast instead of prompting.
ideon delete in non-TTY requires --force after user confirmation.--export on write/resume has no effect during --dry-run.- Export without
--overwrite fails if destination markdown already exists.
- Link enrichment is opt-in on write/resume (
--enrich-links); use ideon links <slug> afterward.
- Custom links (
--link "expr->url") take precedence over generated links and survive --mode fresh.
--max-images <n> caps total images including cover (1=cover only).ideon write traps SIGINT/SIGTERM, patches resume state, exits 130.
Config precedence (highest to lowest): CLI args → job file → IDEON_* env → saved settings → schema defaults. Secrets: env vars override keychain.
Gotchas and sharp edges
- Non-interactive runs fail if style/intent/length/targets are missing — pass all required flags or job settings.
- Keychain unavailable in containers — set
TELEPAT_DISABLE_KEYTAR=true and use env secrets.
- Legacy
xMode fields in content targets are rejected — use x-post or x-thread.
- Resume works from any directory — session state is in OS config dir, keyed by project path.
- Queue entries store full publication/series snapshots — deleting a publication does not update queued entries.
--from-queue with --export uses stored export path unless overridden at write time.- Plan without
--auto-save: present stdout results and ask user before persisting.
Failure handling
| Failure | Action |
|---|
| No idea provided | Ask for idea or require --job with idea/prompt. |
| Missing required options in non-interactive mode | Add --primary, --style, --intent, and --length. |
| Keychain unavailable | Set TELEPAT_DISABLE_KEYTAR=true and use env secrets. |
| No resumable session found | Start a fresh ideon write ... run. |
| Preview cannot find markdown | Run write first or pass explicit .md path. |
| Invalid target spec | Use <content-type=count>; primary count exactly 1. |
| Export destination already exists | Pass --overwrite or choose a different directory. |
| Generation not found for export | Run ideon article list to find slugs/IDs. |
| No pending articles in queue | Add with ideon queue add or remove --publication filter. |
| Queue entry claimed by another process | --from-queue skips to next pending entry. |
| Plan exit code 2 | Topic exhausted — present pivot suggestions from stdout. |
Companion references
