@alavida/cli

Command-line interface and MCP server for the Alavida platform. Browse the component registry, install AI-powered workflows as Claude Code skills, monitor jobs, and manage credits — all from the terminal. The bundled MCP server lets AI assistants discover and operate components conversationally.

Installation

# Global install
npm install -g @alavida/cli

# Or run directly with npx (no install required)
npx @alavida/cli <command>

Requires Node.js >= 18.

Quick Start

# 1. Authenticate with your API key
alavida auth

# 2. Browse available components
alavida registry

# 3. Install a component
alavida add buying-signals

# 4. Check your credit balance
alavida credits

# 5. Monitor running jobs
alavida jobs watch

Authentication

Authenticate by providing a Clerk API key (created via the dashboard at /api-keys). The key is stored locally in ~/.config/alavida/config.json with restrictive file permissions (0600).

# Interactive — prompts for your API key
alavida auth

# Check current auth status
alavida auth status

auth status displays your email, team name, credit balance, and key suffix (last 4 chars). It validates the key against the platform API and reports if the key is invalid or expired.

All commands that require authentication will check for a valid key first and prompt you to authenticate if one is missing.

Commands Reference

alavida auth

Authenticate with the Alavida platform using a Clerk API key.

alavida auth                    # Interactive prompt

alavida auth status

Display current authentication status.

alavida auth status

Output:

  Email:    [email protected]
  Team:     Alavida
  Balance:  10,000 credits
  API Key:  ...a1b2

alavida registry

Browse the component registry. No authentication required.

alavida registry
alavida registry --category prospecting
alavida registry --type workflow

| Flag | Description | |------|-------------| | --category <category> | Filter by component category | | --type <type> | Filter by type: workflow or tool |

Output is a table with columns: Slug, Name, Type, Category, Price. Installed components are marked with [installed].

alavida search <query>

Search the registry by keyword.

alavida search "buying signals"
alavida search "prospect enrichment"

Output is a table with columns: Slug, Name, Description, Category, Price.

alavida add <component>

Install a component from the registry. Delegates to skills.sh (npx skills add <source> -y) to install skill files across all supported AI agents (Claude, Cursor, Codex, OpenCode, Windsurf). Triggers authentication if not already authenticated.

alavida add buying-signals

If the component is already installed at the same version, displays a message suggesting alavida update instead. After installation, shows the list of installed files and next steps.

alavida remove <component>

Remove an installed component. Delegates to skills.sh (npx skills remove <slug> -y) to remove skill files from all AI agents. Cloud data (job history, results) is not affected.

alavida remove buying-signals

Prompts for confirmation before removing.

alavida update [component]

Update installed components to their latest versions. If no component is specified, checks all installed components.

alavida update                  # Update all installed components
alavida update buying-signals   # Update a specific component

For each component, fetches the latest version from the registry, compares it with the installed version, and re-installs via skills.sh if a newer version is available.

alavida list

List all locally installed components with version and update status.

alavida list

Output is a table with columns: Slug, Installed (version), Latest (version), Status, Installed (date), Path.

alavida jobs

List recent jobs across all components. Requires authentication.

alavida jobs
alavida jobs --status completed
alavida jobs --component buying-signals --limit 5

| Flag | Description | |------|-------------| | --status <status> | Filter by status: queued, processing, completed, failed, cancelled | | --component <slug> | Filter by component slug | | --limit <n> | Number of jobs to show (default: 20) |

Output is a table with columns: Job ID (truncated), Component, Status, Created, Duration, Credits.

alavida jobs status <id>

Show detailed information about a specific job.

alavida jobs status abc12345-...

Output varies by job status:

• Completed: shows duration, credits charged, and a preview of the result payload
• Processing: shows elapsed time and suggests using alavida jobs watch
• Failed: shows error code and error message

If the job charged credits and the remaining balance is below 500, a low credit warning is displayed.

alavida jobs watch

Watch active jobs in real-time. Polls for status changes and displays state transitions as they happen.

alavida jobs watch
alavida jobs watch --interval 5

| Flag | Description | |------|-------------| | --interval <seconds> | Polling interval in seconds, 1-30 (default: 3) |

Output shows state transitions as they occur:

  [10:30:15] abc12345 buying-signals: queued -> processing
  [10:30:21] abc12345 buying-signals: processing -> completed

Exits automatically when no active jobs remain, or press Ctrl+C to stop.

alavida credits

View credit balance and recent usage history. Requires authentication.

alavida credits

Output:

  Balance:          8,500 credits
  Lifetime Added:   10,000 credits
  Lifetime Used:    1,500 credits

  Recent charges:
  | Job      | Credits | Date          |
  | abc12345 | 150     | 2 hours ago   |
  | def67890 | 200     | 1 day ago     |

Displays a warning if balance is below 500 credits, or an error if balance is zero, with a link to purchase more.

alavida run <slug>

Run a component (tool or workflow). Requires authentication.

alavida run echo --action ping --input '{"message": "hello"}'
alavida run buying-signals --input '{"companies": ["Acme Corp"]}'

| Flag | Description | |------|-------------| | --action <action> | Tool action to execute (required for tools) | | --input <json> | JSON input payload |

alavida schema <slug>

Fetch and display a component's input/output schema.

alavida schema buying-signals

alavida onboard <slug>

Interactive onboarding for a component — fetches schema, shows pricing, and guides through first run.

alavida onboard buying-signals

alavida mcp

Start the MCP server over stdio transport. Not intended for direct invocation — configure it in your .mcp.json file (see MCP Integration below).

alavida mcp

MCP Integration

Add the Alavida MCP server to your Claude Code configuration in .mcp.json:

{
  "mcpServers": {
    "alavida": {
      "command": "npx",
      "args": ["@alavida/cli", "mcp"]
    }
  }
}

The MCP server exposes 10 tools for AI assistant interaction:

| Tool | Description | Inputs | |------|-------------|--------| | run_component | Run a component (tool or workflow) | slug: string, action?: string, input?: object | | get_component_schema | Get a component's input/output schema | slug: string | | search_registry | Search the component registry by keyword | query: string | | list_registry | List all components with optional filters | category?: string, type?: string | | get_component | Get full details for a specific component | slug: string | | install_component | Install a component's skill files locally | slug: string | | list_jobs | List recent jobs with optional filters | status?: string, component?: string, limit?: number | | check_job | Check status and results of a specific job | job_id: string | | get_credits | Get current credit balance and stats | (none) | | list_installed | List locally installed components | (none) |

All tools that require authentication read the API key from ~/.config/alavida/config.json. If not authenticated, install_component triggers an interactive auth prompt.

Configuration

The CLI stores configuration at ~/.config/alavida/config.json. The file is created with mode 0600 (user-only read/write) and the directory with mode 0700.

{
  "api_key": "<clerk-api-key>",
  "api_url": "https://api.alavida.ai",
  "email": "[email protected]",
  "team_id": "team_...",
  "team_name": "Alavida",
  "installed_components": {
    "buying-signals": {
      "slug": "buying-signals",
      "version": "1.0.0",
      "installed_at": "2026-02-15T10:30:00Z",
      "skill_source": "alavida-ai/skills@buying-signals"
    }
  }
}

| Field | Description | |-------|-------------| | api_key | Clerk API key (required, from dashboard /api-keys) | | api_url | API base URL (optional, defaults to https://api.alavida.ai) | | email | Authenticated user's email | | team_id | Team identifier | | team_name | Team display name | | installed_components | Map of installed component slugs to metadata |

Development

Prerequisites

• Node.js >= 18
• pnpm 9.15+

Build

# From the repo root
pnpm install
pnpm --filter @alavida/cli build

# Or from packages/cli
cd packages/cli
pnpm build

Watch mode

pnpm --filter @alavida/cli dev

Project structure

packages/cli/
├── bin/
│   └── alavida.js              # Executable entry point (shebang)
├── src/
│   ├── index.ts                # CLI setup (Commander.js program)
│   ├── types.ts                # CLI-specific TypeScript types
│   ├── commands/
│   │   ├── auth.ts             # alavida auth, alavida auth status
│   │   ├── registry.ts         # alavida registry
│   │   ├── search.ts           # alavida search <query>
│   │   ├── add.ts              # alavida add <component>
│   │   ├── remove.ts           # alavida remove <component>
│   │   ├── update.ts           # alavida update [component]
│   │   ├── list.ts             # alavida list
│   │   ├── jobs.ts             # alavida jobs, alavida jobs status <id>
│   │   ├── watch.ts            # alavida jobs watch
│   │   └── credits.ts          # alavida credits
│   ├── lib/
│   │   ├── api-client.ts       # HTTP client wrapping native fetch
│   │   ├── auth.ts             # API key validation, storage, auth flow
│   │   ├── config.ts           # Config file read/write (~/.config/alavida/)
│   │   ├── skills.ts           # skills.sh wrapper (npx skills add/remove)
│   │   └── output.ts           # Terminal formatting (tables, colors, time)
│   └── mcp/
│       ├── server.ts           # MCP server (stdio transport)
│       └── tools/              # Individual MCP tool implementations
├── package.json
├── tsconfig.json
└── tsup.config.ts              # Build config (ESM, Node 18 target)

Key dependencies

| Package | Purpose | |---------|---------| | commander | CLI framework with subcommand support | | chalk | Terminal string coloring | | cli-table3 | Formatted table output | | @modelcontextprotocol/sdk | Official MCP TypeScript SDK | | @alavida/database | Drizzle schema and DB types (workspace dependency, build-time only) |