article-os

SERP-driven SEO article writing CLI. Analyzes ranking pages, builds a research-backed brief, runs semantic gap analysis, validates against quality gates, and produces a final article ready for publishing.

Install

Two ways to get started.

Option A — clone this repo (recommended for non-terminal users)

Click Use this template on the GitHub page (or git clone), then:

cd article-os
npm install
node bin/article-os.js init           # interactive credential setup

Inside the cloned repo, .claude/commands/article/ is already discovered by Claude Code, so /article:* slash commands are immediately available.

Option B — global npm install

npm install -g article-os
article-os init                       # interactive credential setup
article-os install-skills             # install the article-os skill into ~/.claude/skills/
article-os install-commands           # install /article:* slash commands
# or, to follow package upgrades automatically:
article-os install-skills --symlink
article-os install-commands --symlink

Requires Node 20+. The skill lets Claude auto-invoke article-os when you ask for SEO articles, briefs, or competitor analysis — no need to remember slash commands. The slash commands give you precise manual control over each phase. Use either or both.

install-skills and install-commands are required for Claude Code to see the files outside this package: npm install ships them, but Claude Code only scans ~/.claude/skills/, ~/.claude/commands/, and the current project's .claude/ folder.

Quickstart

# 1. Save credentials to .env (or pass them as flags)
article-os init
# non-interactive variant for scripts/CI:
article-os init --dataforseo-login X --dataforseo-password Y --force

# 2. Generate a brief
article-os brief my-client "your focus keyword" --with-serp

# 3. Review and approve the brief
article-os approve briefs/<file>.md

# 4. The brief is ready. Write the article with your preferred LLM workflow.

Commands

| Command | Purpose | |---------|---------| | article-os brief <client> "<keyword>" [--with-serp] [--competitor <url>...] | Generate SERP-driven brief with competitor extraction and keyword context | | article-os context <client> "<keyword>" <files...> | TF-IDF + BM25 + n-gram analysis on competitor texts | | article-os approve <brief-file> [--force] | Flip brief status from da approvare to approvato | | article-os status <brief-file> | Print current approval state (exit 0 if approved, 3 otherwise) | | article-os init [--dataforseo-login X] [--dataforseo-password X] [--anthropic-key X] [--force] | Interactive (or flag-driven) credential setup. Writes .env in the current directory with mode 0600 | | article-os install-commands [--project] [--symlink] [--force] | Install bundled /article:* slash commands into ~/.claude/commands/article/ (default), the current repo (--project), or via symlink that follows package upgrades (--symlink) | | article-os install-skills [--project] [--symlink] [--force] | Install the bundled article-os skill into ~/.claude/skills/article-os/ (default), the current repo (--project), or via symlink (--symlink). The skill auto-triggers when you ask Claude to write a SEO article or build a brief | | article-os rules | Print the canonical rule count | | article-os doctor | Verify workspace integrity (42 checks) | | article-os viewer | Launch the local artifact dashboard |

Add --json to any command for machine-readable output.

Workflow

SERP → headings → structure → contents → keyword context
  → brief → approval gate → draft → gap analysis → revision
  → validation → final

The CLI handles the deterministic phases:

• SERP fetch via DataForSEO
• competitor page extraction (titles, H1/H2/H3, body, word count)
• keyword-context analysis (TF-IDF, BM25, bigrams, trigrams, context windows)
• 281 operational rules grouped by phase

The drafting, gap analysis, and validation phases are typically driven by an LLM that consumes the CLI artifacts as inputs.

Configuration

DataForSEO

Required for --with-serp. Get credentials at https://dataforseo.com/. Pass them as environment variables or a local .env file:

DATAFORSEO_LOGIN=your-api-login
DATAFORSEO_PASSWORD=your-api-password

Client context

For consistent brand voice, audience, and tone across runs, create a client file at clients/<slug>/context.yaml:

client_slug: my-client
brand_name: My Brand
sector: my-sector
language: it
country: Italy
audience:
  primary: target audience description
tone_of_voice:
  register: neutral, fact-first
editorial_profile: compliance-press   # or omit for standard

Editorial profiles

compliance-press is the built-in profile for regulated topics (finance, health, legal, insurance, threshold-rich informational content). It enforces neutral wording, visible numbers/dates/thresholds, source-sensitive claims, and a "what to know → what to do" ordering.

Outputs

briefs/                 generated briefs (.md)
competitors/            competitor set + extracted data (.md, .json)
research/               keyword context analysis (.md, .json)
findings/               operational findings per run (.json)
operations/             operations per run (.json)
articles/               final articles
reports/                validation and workflow reports
history/articles/       machine-readable run snapshots

Approval gate

Briefs are written with Status: da approvare and must be explicitly approved before downstream commands proceed:

article-os approve briefs/2026-05-26-my-client-my-keyword-brief.md
article-os status briefs/2026-05-26-my-client-my-keyword-brief.md
# → approvato (exit 0)

Already-approved briefs are a no-op; re-approve with --force.

License

MIT.