Nexlem Commands Reference

Authoritative reference for all 31 commands in src/commands/. Commands are grouped by user workflow — read top-to-bottom to follow the operator's typical encounter order, or jump to a section for targeted reference.

Commands are invokable two ways:

• Claude Code skill form (/nexlem <cmd>): the operator-facing surface; what /nexlem setup installs
• Bun CLI form (bun run src/main.ts <cmd> or bun nexlem <cmd>): the underlying executable; what the skills shell out to

Both forms accept the same flags. Where this reference shows a flag table, it applies to both invocation forms. Skill files in .claude/skills/ provide the conversational UX; the Bun CLI provides the deterministic exit codes and --json shapes.

Conventions

• All list and show commands support --json for machine-readable output (CLAUDE.md skill rule)
• Multi-status filters use comma-separated values: --status queued,paused (CLAUDE.md skill rule)
• Compound flags: --run on create combines campaign creation + immediate start (CLAUDE.md skill rule)
• Exit codes: 0 = success, 1 = error (with stderr message); per-command additions noted in each section
• Every command supports --help for inline usage

Setup

The three commands you run once per project (or once per workspace, for setup).

init

Purpose: Initialize a new Nexlem project in the current directory. Runs the four-section configuration wizard (project, business, main-site, gates) and writes .nexlem/ state directory, SQLite database, and config/ files.

Synopsis: bun nexlem init [--name <name>] [--lang <code>] [--site-url <url>] [--business <name>]

Flags:

Example:

/nexlem init
bun nexlem init --name "Achecar" --lang "pt-BR" --site-url "https://achecar.com.br" --business "Achecar"

Outputs: Creates .nexlem/, .nexlem/nexlem.db (SQLite state), config/project.jsonc, config/business.jsonc, config/main.jsonc, .env template (if absent).

Exit codes: 0 on success, 1 if the directory is already a Nexlem project (.nexlem/ exists) or if wizard setup fails.

setup

Purpose: Install the Nexlem skill files, hooks, and rules into the current Claude Code workspace. Run once per workspace — not once per project. Installs .claude/hooks/nexlem-guard.sh and registers it in .claude/settings.json.

Synopsis: /nexlem setup [check]

Actions:

Flags: None beyond subcommand.

Example:

/nexlem setup
bun nexlem setup check

Exit codes: 0 on success, 1 if .claude/ is read-only or installation fails.

reconfigure

Purpose: Re-run the configuration wizard against an existing project. Emits current values as JSON for the skill's AskUserQuestion picker, then the skill calls wizard-write --mode reconfigure to apply changes. Supports an opt-in --reset path for destructive data operations.

Synopsis: /nexlem reconfigure [--section <name>] [--reset <type>]

Flags:

Example:

/nexlem reconfigure --section gates
/nexlem reconfigure --reset database

Exit codes: 0 on success (emits JSON on stdout for skill consumption), 1 on invalid section name or reset type.

Campaigns

The lifecycle of a content campaign: start, inspect, resume, complete.

run

Purpose: Start a new campaign or resume the most recent interrupted one. Dispatches the full pipeline DAG appropriate to --type. Creates the campaign row, scaffolds the campaign directory, and runs all pipeline stages sequentially. Auto-resumes if an interrupted campaign is found.

Synopsis: /nexlem run [<topic>] [--type <type>] [--site <slug>] [--from-campaign <id>] [--batch] [--dry-run] [--group-to-sites <slug1,slug2,...>]

Flags:

Campaign type stages:

Examples:

/nexlem run "Hyundai HB20 review" --site achecar --type full
/nexlem run --type social-only --from-campaign H5xF3kly6_SwIIH7KfRGv
/nexlem run --batch
/nexlem run --batch --dry-run
/nexlem run --group-to-sites achecar,moto-site "Honda CG review"

Exit codes: 0 on completion (full pipeline OR graceful interrupt), 1 on configuration error or unrecoverable pipeline failure. Batch mode exits 1 if any campaign fails.

campaign

Purpose: Campaign CRUD — create, list, show, retry, delete, and manage campaign metadata. Use this when you want to queue campaigns ahead of time; /nexlem run creates and immediately starts in one step.

Synopsis: /nexlem campaign <action> [args] [flags]

Actions: create, run, list, show, retry, delete, export, import, lineage, unlink-keyword.

Common flags:

Examples:

/nexlem campaign create --site achecar --topic "Hyundai HB20 review" --keyword "hyundai hb20" --type full
/nexlem campaign list --status running,paused --json
/nexlem campaign show H5xF3kly6_SwIIH7KfRGv
/nexlem campaign retry H5xF3kly6_SwIIH7KfRGv
/nexlem campaign delete H5xF3kly6_SwIIH7KfRGv

--json shape (list):

[
  {
    "id": "H5xF3kly6_SwIIH7KfRGv",
    "topic": "Hyundai HB20 review",
    "site_slug": "achecar",
    "campaign_type": "full",
    "status": "completed",
    "created_at": "2026-05-16T10:00:00.000Z",
    "quality_score": 0.92
  }
]

--json shape (show):

{
  "id": "H5xF3kly6_SwIIH7KfRGv",
  "topic": "Hyundai HB20 review",
  "site_slug": "achecar",
  "campaign_type": "full",
  "status": "completed",
  "quality_score": 0.92,
  "config_path": ".nexlem/campaigns/achecar/H5xF3-hyundai-hb20-review",
  "created_at": "2026-05-16T10:00:00.000Z",
  "updated_at": "2026-05-16T12:00:00.000Z",
  "steps": [
    {
      "agent_name": "research",
      "agent_order": 1,
      "agent_version": "1.0.0",
      "status": "completed",
      "duration_ms": 12345,
      "last_error": null,
      "output_path": ".nexlem/campaigns/achecar/H5xF3.../steps/01-research.json"
    }
  ]
}

The agent_version field on each step (added in Phase 41 DOCV2-04) is the semver of the agent prompt that produced this step's output. Pre-Phase-41 step rows have agent_version: null (no backfill per D-41-04).

Exit codes: 0 on success, 1 on unknown action / campaign not found / invalid arguments.

run-init

Purpose: Skill-internal pre-pipeline setup invoked by the /nexlem run skill flow. Creates the campaign row, validates config, and returns the campaign id + directory paths as JSON. Operators rarely invoke directly; use for recovery scripting.

Synopsis: bun nexlem run-init <topic> [<site-slug>]

Flags: None beyond positional arguments.

Example:

bun nexlem run-init "Hyundai HB20 review" achecar

Exit codes: 0 on success (emits JSON with campaign_id and directory paths), 1 on config error or missing project.

run-complete

Purpose: Skill-internal post-pipeline cleanup invoked by the /nexlem run skill flow. Finalizes campaign status, records quality score, and writes a run summary.

Synopsis: bun nexlem run-complete --campaign-id <id> [--quality-score <score>]

Flags:

Example:

bun nexlem run-complete --campaign-id H5xF3kly6_SwIIH7KfRGv --quality-score 0.92

Exit codes: 0 on success, 1 on unknown campaign or DB error.

run-paths

Purpose: Emit the filesystem paths the /nexlem run skill flow needs: DB path, campaigns base dir, and config dir. Respects NEXLEM_DB, NEXLEM_CAMPAIGNS_DIR, and NEXLEM_CONFIG_DIR env var overrides (UAT isolation).

Synopsis: bun nexlem run-paths

Flags: None.

Example:

bun nexlem run-paths

--json shape (stdout):

{
  "db_path": "/path/to/.nexlem/nexlem.db",
  "campaigns_base_dir": "/path/to/campaigns",
  "config_dir": "/path/to/config"
}

Exit codes: 0 always.

Inspection

The five commands for understanding what Nexlem has done.

status

Purpose: Overall project status — running campaigns, queued work, recent completions, site list, DB health, and framework version. Supersedes the v1.5 morning and combined health/dashboard surfaces.

Synopsis: /nexlem status

Flags: None (plain text output only).

Example:

/nexlem status

Output includes: Project name, language, framework version; sites configured; campaign counts by status; active/paused campaign details with step-level progress; health check results; database summary.

Exit codes: 0 always (read-only; never fails on data).

health

Purpose: Standalone system-health check — DB connectivity and integrity, config validity, agent file integrity, orphaned campaigns, disk usage. Suitable for scripted health monitoring and CI.

Synopsis: /nexlem health [--json]

Flags:

Example:

/nexlem health
/nexlem health --json

--json shape:

{
  "checks": [
    { "name": "db_integrity", "status": "pass", "detail": "ok" },
    { "name": "config_valid", "status": "pass" },
    { "name": "sites_valid", "status": "pass", "detail": "1 sites checked" },
    { "name": "env_present", "status": "pass", "detail": ".env file found" },
    { "name": "orphan_campaigns", "status": "pass", "detail": "0 orphans" },
    { "name": "failed_campaigns", "status": "warn", "detail": "2 failed campaigns" }
  ],
  "disk": {
    "nexlem_bytes": 1048576,
    "db_bytes": 204800,
    "campaigns_bytes": 843776
  }
}

Exit codes: 0 if all health checks pass, 1 if any check has status fail (use in CI or cron). warn checks do not trigger exit 1.

agent-list

Purpose: Machine-readable catalog of all pipeline agents. Used by skill hooks for validation and by operators verifying which agents are available and at which prompt version.

Synopsis: bun nexlem agent-list --json

Flags:

Examples:

bun nexlem agent-list --json
bun nexlem agent-list --json | jq '.[] | select(.channel == "blog") | .name'
bun nexlem agent-list --json | jq '.[] | {name, version}'

--json shape: Array of agent entries sorted by (channel, order):

[
  {
    "name": "research",
    "order": 1,
    "version": "1.0.0",
    "channel": "blog",
    "executor": "real",
    "campaign_types": ["full", "blog-only", "refresh", "silo-cluster"]
  },
  {
    "name": "carousel",
    "order": 11,
    "version": "1.0.0",
    "channel": "social",
    "executor": "real",
    "campaign_types": ["full", "social-only"]
  }
]

The version field (added in Phase 41 DOCV2-04) is the semver tag of the agent's prompt at query time, bumped per D-41-03 on any change to agents/<name>.md.

Exit codes: 0 on success, 1 if --json is missing (the only supported invocation).

metrics

Purpose: Per-agent and per-campaign performance metrics — durations, retry rates, quality-gate verdict distribution, content volume by site and ISO week.

Synopsis: /nexlem metrics <subcommand> [flags]

Subcommands:

Flags (agents / campaigns / volume):

Flags (file):

Examples:

/nexlem metrics agents --site achecar --since 7d
/nexlem metrics campaigns --json
/nexlem metrics volume
/nexlem metrics file .nexlem/campaigns/achecar/.../steps/01-research.json

Exit codes: 0 always.

dashboard

Purpose: TUI-style project overview rendered in the terminal — campaign counts, active pipeline summary, disk usage. Largely superseded by /nexlem status; retained for operators who prefer the dashboard surface.

Synopsis: /nexlem dashboard [--json]

Flags:

Example:

/nexlem dashboard
/nexlem dashboard --json

Exit codes: 0 always.

Content & Editorial

The seven commands for inspecting and managing produced content and editorial planning.

content

Purpose: Browse and analyze completed campaign outputs. Subcommands expose stale content detection (stale), site-level content audit (audit), and direct step file inspection.

Synopsis: /nexlem content <action> [args] [flags]

Actions:

Flags (stale):

Flags (audit):

Examples:

/nexlem content stale --site achecar --days 60
/nexlem content audit --site achecar
/nexlem content audit --site achecar --json

Exit codes: 0 on success, 1 on missing required flag or DB error.

atom

Purpose: Browse the atom library — reusable content atoms (quotes, stats, definitions, examples, checklists) extracted by the atomizer agent from completed campaigns.

Synopsis: /nexlem atom <action> [flags]

Actions: list.

Flags:

Example:

/nexlem atom list --type stat --site achecar --limit 20
/nexlem atom list --json

Exit codes: 0 on success.

atom-context

Purpose: Build the atom-context string passed to social agents — a compact summary of the available atoms for a campaign. Skill-internal; operators rarely invoke directly.

Synopsis: bun nexlem atom-context --campaign-id <id>

Flags:

Example:

bun nexlem atom-context --campaign-id H5xF3kly6_SwIIH7KfRGv

Exit codes: 0 on success (emits atom context string on stdout), 1 on unknown campaign.

calendar

Purpose: Editorial calendar — scheduled content queue across sites. Status lifecycle: planned → drafting → published → cancelled. Supports planning new entries, viewing the queue, linking entries to running campaigns, and auto-planning from keyword lists.

Synopsis: /nexlem calendar <action> [args] [flags]

Actions:

Flags (view):

Flags (plan):

Flags (auto-plan):

Examples:

/nexlem calendar view --site achecar --weeks 4
/nexlem calendar view --status planned,drafting
/nexlem calendar plan --site achecar --topic "Hyundai HB20 fuel economy" --keyword "hb20 consumo" --date 2026-06-01
/nexlem calendar link entry-123 H5xF3kly6_SwIIH7KfRGv
/nexlem calendar auto-plan --site achecar --weeks 4

Exit codes: 0 on success, 1 on missing required flags or invalid date.

keywords

Purpose: Keyword expansion and management. Wraps the keyword-expander orchestrator agent (LLM-only, no external paid APIs). Supports dry-run expansion for review and --write for persisting suggestions directly to the editorial calendar.

Synopsis: /nexlem keywords <action> [args] [flags]

Actions: expand.

Flags (expand):

Examples:

/nexlem keywords expand "hyundai hb20" --count 10 --site achecar
/nexlem keywords expand "hyundai hb20" --write --site achecar --date 2026-06-01

Exit codes: 0 on success, 1 on missing required flags or invalid JSON (when piping for --write).

silo

Purpose: Content silo planning — pillar + cluster topology. Wraps the silo-advisor orchestrator agent to suggest a silo structure and then executes the silo campaign orchestration across pillar + cluster campaigns.

Synopsis: /nexlem silo <action> [args] [flags]

Actions:

Flags (plan):

Flags (list):

Examples:

/nexlem silo plan "small SUVs" --site achecar
/nexlem silo list --site achecar
/nexlem silo status silo-id-123
/nexlem silo run silo-id-123

Exit codes: 0 on success, 1 on unknown silo or invalid advisor output.

site

Purpose: Site management — add a new site, list configured sites, show one site's config.

Synopsis: /nexlem site <action> [args] [flags]

Actions: add, list.

Flags (add):

Examples:

/nexlem site list
/nexlem site add --slug achecar --url https://achecar.com.br --role primary --relationship owner

Exit codes: 0 on success, 1 on invalid role / relationship / missing required flags.

Pipeline Operations

Lower-level commands that operate on the pipeline directly. Most operators rarely invoke these — they are wrapped by /nexlem run.

pipeline

Purpose: Direct pipeline analytics and diagnostics — per-agent timing stats, bottleneck analysis, retry statistics. Does not execute the pipeline; use /nexlem run for execution.

Synopsis: bun nexlem pipeline <subcommand> [flags]

Subcommands:

Flags (all subcommands):

Examples:

bun nexlem pipeline stats
bun nexlem pipeline stats --agent writer --json
bun nexlem pipeline bottleneck --json
bun nexlem pipeline retry-stats

Exit codes: 0 on success, 1 on unknown subcommand.

quality-check

Purpose: Run the quality-gate agent against a campaign's existing output without re-running upstream stages. Useful for re-checking quality after manual edits to a step output file.

Synopsis: bun nexlem quality-check --campaign-id <id> [--article-path <path>]

Flags:

Example:

bun nexlem quality-check --campaign-id H5xF3kly6_SwIIH7KfRGv

Exit codes: 0 if verdict is APROVADO (approved), 1 if NÃO APROVADO or if the check fails to run.

publish-blog

Purpose: Render a completed, quality-approved campaign's blog markdown to the configured publish output directory. In v2.0 the publish target is a local directory hand-off — the operator copies or syncs from there to their CMS. There is no external CMS integration.

Synopsis: bun nexlem publish-blog --campaign-id <id> [--force] [--force-publish]

Flags:

Cannibalization policy:

• warn (default): prints a warning and publishes; exit 0.
• block: prints warning + error and exits with code 2. Use --force-publish to override.

Example:

bun nexlem publish-blog --campaign-id H5xF3kly6_SwIIH7KfRGv
bun nexlem publish-blog --campaign-id H5xF3kly6_SwIIH7KfRGv --force-publish

Exit codes: 0 on success, 1 on unknown campaign / campaign not yet APROVADO / write failure, 2 on cannibalization block.

Skill Internals

These commands are invoked by the /nexlem skill flows in .claude/skills/. Operators rarely need them directly, but they are documented here for skill authors and recovery scenarios. Per D-41-09: better to document than hide — operators occasionally need them for recovery.

save-step

Purpose: Persist an agent's completed output to the steps table. Invoked by the pipeline runner after each agent completes. Records output path, duration, and agent version.

Synopsis: bun nexlem save-step --campaign-id <id> --step <name> --output-path <path> --duration-ms <ms>

Flags:

Example:

bun nexlem save-step --campaign-id H5xF3kly6_SwIIH7KfRGv --step research --output-path /path/to/steps/01-research.json --duration-ms 12345

Exit codes: 0 on success, 1 on DB error or missing required flags.

persist-atomizer

Purpose: Two-phase commit hook for the atomizer agent — persists extracted atoms to the atom_library table in the same transaction as the step completion (per Phase 38 D-38-19). Ensures atom rows and the step row are committed atomically.

Synopsis: bun nexlem persist-atomizer --campaign-id <id> --output-path <path>

Flags:

Example:

bun nexlem persist-atomizer --campaign-id H5xF3kly6_SwIIH7KfRGv --output-path /path/to/steps/10-atomizer.json

Exit codes: 0 on success, 1 on contract violation (malformed atomizer JSON) or DB error.

social-init

Purpose: Initialize the social-channel fan-out — sets up the four social agent step slots (carousel, caption, reel-script, youtube-short) in the steps table after the atomizer completes.

Synopsis: bun nexlem social-init --campaign-id <id>

Flags:

Example:

bun nexlem social-init --campaign-id H5xF3kly6_SwIIH7KfRGv

Exit codes: 0 on success, 1 on unknown campaign or DB error.

social-complete

Purpose: Aggregate the four social agents' outputs and finalize the social pipeline status. Records the compliance score if provided.

Synopsis: bun nexlem social-complete --campaign-id <id> [--compliance-score <json>]

Flags:

Example:

bun nexlem social-complete --campaign-id H5xF3kly6_SwIIH7KfRGv

Exit codes: 0 on success, 1 if any social agent did not complete or if --compliance-score is invalid JSON.

wizard-schema

Purpose: Emit the wizard's question schema for a given section as JSON. Used by skill files to render AskUserQuestion prompts and by nexlem-guard.sh to validate section IDs without hardcoding.

Synopsis: bun nexlem wizard-schema [--section <id>] [--list]

Flags:

Examples:

bun nexlem wizard-schema --list
bun nexlem wizard-schema --section project
bun nexlem wizard-schema --section business --answers '{"name":"Achecar"}'

Exit codes: 0 on success, 1 on unknown section id (use --list to enumerate valid ids).

wizard-write

Purpose: Write the wizard's collected answers to config files. Counterpart to wizard-schema (read). Accepts a four-section payload and renders config/project.jsonc, config/business.jsonc, config/main.jsonc, and config/gates.json. Supports --mode reconfigure for non-destructive updates to an existing project.

Synopsis: bun nexlem wizard-write [--mode <mode>]

Flags:

Input: Reads a JSON payload from stdin containing the sections array with sectionId + answers for each of the four wizard sections.

Example:

echo '<wizard-payload-json>' | bun nexlem wizard-write
echo '<wizard-payload-json>' | bun nexlem wizard-write --mode reconfigure

Exit codes: 0 on success, 1 on Zod schema validation failure (malformed payload or missing sections).

next

Purpose: Suggest the operator's next action based on current state — surfaces the highest-priority pending item (interrupted campaign, queued campaign, unlinked calendar entries). Backs the /nexlem next skill flow.

Synopsis: /nexlem next [--all]

Flags:

Examples:

/nexlem next
/nexlem next --all

Exit codes: 0 always (advisory only; never fails on data).

backup

Purpose: Snapshot .nexlem/nexlem.db and config/ to a timestamped archive in .nexlem/backups/. Also supports listing backups and restoring from a previous snapshot.

Synopsis: /nexlem backup <action> [args]

Actions:

Flags: None beyond subcommand and arguments.

Examples:

/nexlem backup create
/nexlem backup list
/nexlem backup restore 2026-05-16

Exit codes: 0 on success, 1 on filesystem error or no matching backup found for restore.

See Also

• docs/GETTING_STARTED.md — first-campaign walkthrough using the real Phase 40 UAT artifacts (Achecar / "Hyundai HB20 review", campaign id H5xF3kly6_SwIIH7KfRGv)
• docs/CONFIG.md — configuration schema including the agent frontmatter spec and version: field
• docs/AGENTS.md — the 16-agent pipeline surface in detail, including v1.0.0 baseline and frontmatter contract

Edit this page on GitHub