​

Alfa CLI

Alfa ships a public CLI package for teams that want the same brand, topic, and article workflow from the terminal.

​

Install

npm install -g @alfaai/cli
alfa --help
alfa --version

The package also bundles starter files under examples/, including a brand JSON example and a topic CSV example.

​

API Base

By default, the CLI targets:

https://app.writealfa.com/api/cli/v1

For local development, point it at a local Alfa app:

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

​

Authentication

The CLI supports browser-based device auth as well as direct token flows.

alfa auth login
alfa auth whoami
alfa auth logout

If your terminal cannot open the browser automatically:

alfa auth login --no-open

​

Brand Setup

Create and inspect brands from JSON files:

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

The brand payload mirrors the app’s model and can include:

• website URL
• voice profile
• voice samples
• target audience
• writing guidelines
• products
• competitors
• CTA goal
• internal links

​

Topic Discovery and Import

​

Discover Topics

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

Detached flow:

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

​

Import Topics

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

CSV imports require:

• title
• primary_keyword

Optional columns include:

• funnel_stage
• secondary_keywords
• topic_type
• search_intent

​

Article Generation

Generate from a keyword:

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 a saved topic:

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

Useful variants:

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

The CLI currently supports:

• markdown
• html
• text
• json

Use JSON when another system needs the structured article payload and metadata rather than rendered text only.

​

Quota

Check your current limits and remaining capacity:

alfa quota

​

When the CLI Is the Better Fit

Use the CLI when you want:

• repeatable brand setup
• topic discovery from scripts
• article generation in batch workflows
• export into repositories or custom pipelines
• a workflow that does not depend on the browser UI