Alfa CLI

Command line interface for Alfa SEO workflows.

Install

npm install -g @alfaai/cli

The package installs the alfa executable.

alfa --help
alfa --version

The package also bundles starter files under examples/:

• examples/brand.example.json
• examples/topics.example.csv

Configure

By default, the CLI talks to the production Alfa API at https://app.writealfa.com/api/cli/v1. For local development, point the CLI at a local app:

export ALFA_API_BASE_URL=http://localhost:3000/api/cli/v1

Authenticate

alfa auth login
alfa auth whoami

If your terminal cannot open a browser automatically:

alfa auth login --no-open

Brand Setup

Create a brand from a JSON file and make it the active local brand:

alfa brand create --file ./brand.json --use
alfa brand list
alfa brand show

Starter brand.json:

{
  "name": "Acme",
  "is_default": true,
  "context": {
    "brand_name": "Acme",
    "website_url": "https://acme.com",
    "tagline": "Analytics and workflow automation for modern operations teams",
    "voice": {
      "formality": 3,
      "emotion": 2,
      "humor": 1,
      "confidence": 4,
      "perspective": "second-person",
      "summary": "Clear, practical, and confident. Explain tradeoffs directly and avoid hype."
    },
    "voice_samples": [
      "Acme helps operations teams replace spreadsheet-heavy workflows with reliable automations.",
      "Use Acme when you need fewer manual handoffs and better reporting across your pipeline."
    ],
    "target_audience": "Operations leaders and RevOps teams at B2B SaaS companies with 10 to 200 employees.",
    "audience_details": {
      "job_roles": ["Head of Operations", "Revenue Operations Manager", "Marketing Operations Manager"],
      "industries": ["B2B SaaS", "Agencies", "Professional Services"],
      "pain_points": [
        "Too much reporting lives in spreadsheets",
        "Manual lead handoffs create delays",
        "Teams cannot trust pipeline numbers"
      ],
      "sophistication": "intermediate"
    },
    "writing_guidelines": {
      "preferred_terms": [
        { "use": "automation", "instead_of": "magic" },
        { "use": "workflow", "instead_of": "growth hack" }
      ],
      "forbidden_words": ["revolutionary", "game-changing"],
      "style_notes": "Prefer concrete examples over abstract claims."
    },
    "products": ["Workflow automation", "Reporting dashboards", "Pipeline alerts"],
    "competitors": ["HubSpot Operations Hub", "Zapier", "Make"],
    "cta_goal": "Book a demo",
    "internal_links": [
      {
        "url": "https://acme.com/product",
        "anchor_text": "Acme product overview"
      },
      {
        "url": "https://acme.com/pricing",
        "anchor_text": "Acme pricing"
      }
    ]
  },
  "voice_sources": {
    "article_urls": [
      "https://acme.com/blog/revenue-operations-reporting",
      "https://acme.com/blog/automating-lead-routing"
    ],
    "analyzed_at": "2026-04-22T00:00:00.000Z",
    "voice_samples": [
      "Build fewer brittle workflows by standardizing your handoff rules first."
    ]
  }
}

Topic Discovery

Run topic discovery for the active brand:

alfa topics discover
alfa topics show --latest
alfa topics save --latest --name "Topic backlog" --all
alfa topics list

Detached workflow:

alfa topics discover --detach
alfa topics status --generation <generation-id>
alfa topics show --generation <generation-id>

Import CSV or JSON topics:

alfa topics import --file ./topics.csv --name "Imported topics"

CSV files must include title and primary_keyword columns. Optional columns include funnel_stage, secondary_keywords, topic_type, and search_intent.

Starter topics.csv:

title,primary_keyword,funnel_stage,secondary_keywords,topic_type,search_intent
How to automate lead routing without breaking attribution,automate lead routing,mofu,"lead routing automation;crm routing rules;marketing attribution",guide,commercial
Revenue operations dashboard template for SaaS teams,revops dashboard template,tofu,"pipeline dashboard;kpi dashboard for saas;revenue reporting",template,informational
HubSpot Operations Hub alternatives for growing SaaS teams,hubspot operations hub alternatives,bofu,"operations hub alternatives;revops automation tools;workflow automation software",alternative,commercial

Quick import flow:

alfa topics import --file ./topics.csv --name "Starter topics"
alfa topics list

Article Generation

Generate from a keyword with the active brand:

alfa article create --keyword "workflow automation software" --detach
alfa article status --run <run-id>
alfa article watch --run <run-id>
alfa article export --run <run-id> --out article.md

Generate from an imported or discovered topic:

alfa topics show --latest
alfa article create --topic <topic-id> --detach

Useful options:

alfa article create --keyword "revops dashboard template" --word-count 1800 --format how-to-guide
alfa article export --run <run-id> --format html --out article.html
alfa article export --run <run-id> --format text
alfa article export --run <run-id> --format json --out article.json
alfa article list --status completed --limit 10
alfa article retry --run <run-id> --wait

Export formats:

• markdown writes dashboard-style Markdown with frontmatter.
• html writes styled standalone HTML.
• text writes plain text for copy/paste workflows.
• json writes the raw article payload and metadata.

Quota

alfa quota