alphamilk

AI-powered SEO research from your terminal. A standalone CLI that proxies to the Alpha Milk Worker API.

Installation

# Run directly without installing
npx alphamilk --help

# Or install globally
npm install -g alphamilk

Authentication

All commands (except login and logout) require an active session. Authenticate with your access token:

alphamilk login --token <your-token-id>

This creates a session stored at ~/.config/alphamilk/session.json. Sessions expire after 24 hours.

Check your current session:

alphamilk session

Clear your session:

alphamilk logout

Resume a previous session without creating a new one:

alphamilk login --token <tokenId> --session <sessionId>

Commands

login -- Authenticate with your access token

alphamilk login --token <tokenId>
alphamilk login -t <tokenId>
alphamilk login -t <tokenId> --session <sessionId>   # Resume existing session

Calls GET /milk/create-session/<tokenId> and stores the returned session locally. With --session, skips server-side creation and saves the provided session ID directly.

logout -- Clear your session

alphamilk logout

Removes the local session file.

session -- Show current session info

alphamilk session

Displays the session ID, token (truncated), base URL, and expiry.

playbooks -- List available research playbooks

alphamilk playbooks

playbook -- Open a playbook or a specific step

# Get full playbook content
alphamilk playbook competitor-discovery

# Get a specific step's instructions
alphamilk playbook competitor-discovery --step broad-discovery
alphamilk playbook competitor-discovery -s broad-discovery

probe -- Execute a research probe

alphamilk probe serp-google -p keyword=seo -p location_code=2840
alphamilk probe ranked-keywords --param target=example.com

Parameters are passed as repeatable --param key=value (or -p key=value) pairs. The probe is executed via POST /milk/probe/<sessionId>/<slug> with parameters sent as a JSON body.

artifact -- Save, update, and retrieve research artifacts

# Save artifacts (type determines required flags)
alphamilk artifact save --type domains --tags "competitors,direct" --data "example.com,other.com"
alphamilk artifact save --type keywords --tags "step:discovery" --data "seo,ranking"
alphamilk artifact save --type document --title "Analysis" --tags analysis --file ./analysis.md
alphamilk artifact save --type document --title "Notes" --tags notes --content "# Notes..."
alphamilk artifact save --type report --title "Report" --tags report --file ./report.md
alphamilk artifact save --type metrics --tags traffic --file ./metrics.json
alphamilk artifact save --type metrics --tags traffic --data "example.com:45000,other.com:12000"

# Update an existing artifact
alphamilk artifact update <artifactId> --title "New Title"
alphamilk artifact update <artifactId> --file ./updated.md
alphamilk artifact update <artifactId> --content "Updated content"
alphamilk artifact update <artifactId> --data "new.com,updated.com"

# Retrieve and render artifacts
alphamilk artifact get <artifactId>
alphamilk artifact render <artifactId>

# List artifacts with optional filters
alphamilk artifact list
alphamilk artifact list --type domains
alphamilk artifact list --tag competitors

# Get a visualization URL for saved artifacts
alphamilk artifact widget --type domains --tags "competitors,direct"
alphamilk artifact widget --type keywords --tags "step:discovery" --location-code 2840 --language-code en

Artifact types: domains, keywords, document, report, metrics. Tags and data items are comma-separated.

plan -- Save and manage research plans

# Save a plan from an XML file
alphamilk plan save --file ./plan.xml

# View current plan status
alphamilk plan status

# Mark a step as done
alphamilk plan check <stepId>

# Skip a step with an optional reason
alphamilk plan skip <stepId>
alphamilk plan skip <stepId> --reason "Not applicable"

event -- View session events and retrieve cached data

# List session events
alphamilk event list
alphamilk event list --format json --limit 20

# Retrieve a specific event's cached data
alphamilk event get <eventId>

How It Works

The CLI is a thin HTTP proxy. Every command translates to a GET, POST, or PUT request to the Alpha Milk Worker API at https://alphamilk.ai/milk/*. Responses (typically markdown) are printed directly to stdout.

All requests include two custom headers for server-side identification:

• X-AlphaMilk-Client: cli
• X-AlphaMilk-CLI-Version: <version>

Build

# Build the single-file bundle
pnpm build

# Run in development mode (via tsx)
pnpm dev

# Type check
pnpm check

# Run tests
pnpm test

The build uses esbuild to bundle all source into a single dist/cli.js file with a Node.js shebang prepended.

Dependencies

This package is fully standalone with zero @repo/* workspace dependencies.

Runtime dependencies:

• @effect/cli -- Command and option parsing
• @effect/platform -- HTTP client
• @effect/platform-node -- Node.js runtime layer
• effect -- Core Effect library

Dev dependencies:

• esbuild -- Bundler
• vitest -- Test runner
• @effect/vitest -- Effect test utilities