npm package: @mikado-ai/cli
Description: Mikado AI CLI and MCP server — submit transcripts, extract insights, integrate with AI agents
Latest version: 0.3.2

# @mikado-ai/cli

Command-line interface and MCP server for [Mikado AI](https://mikadoai.app) — submit conversation transcripts, extract structured insights, and integrate with AI agents.

## Install

```bash
npx @mikado-ai/cli
```

Or install globally:

```bash
npm install -g @mikado-ai/cli
```

## Quick Start

```bash
# 1. Authenticate (get your API key from Mikado AI → Settings → API Keys)
mikado auth

# 2. See available campaigns
mikado campaigns

# 3. Submit a transcript
mikado submit transcript.txt --campaign 928721aa
```

## Authentication

### Interactive

```bash
mikado auth
```

You'll be prompted for your API key and server URL.

### Non-Interactive

```bash
mikado auth --key mkd_your_api_key --url https://mikadoai.app
```

### Environment Variable

```bash
export MIKADO_API_KEY=mkd_your_api_key
export MIKADO_URL=https://mikadoai.app
```

Environment variables take precedence over the config file.

### Config File

Credentials are stored in `~/.mikado/config.json`. The file is created with restricted permissions (owner-only read/write).

## Commands

### `mikado submit <file>`

Submit a conversation transcript for processing. By default, waits for results.

```bash
# Submit and wait for results (default)
mikado submit transcript.txt --campaign 928721aa

# Submit without waiting
mikado submit transcript.txt --campaign 928721aa --no-wait

# Read from stdin
cat transcript.txt | mikado submit -

# JSON output for scripting
mikado submit transcript.txt --campaign 928721aa --json

# Custom timeout (default: 300s)
mikado submit transcript.txt --timeout 60
```

**Options:**

| Flag | Description |
|------|-------------|
| `-c, --campaign <id>` | Campaign UUID, UUID prefix, or name |
| `--no-wait` | Return immediately with job ID |
| `--timeout <seconds>` | Max wait time (default: 300) |
| `--json` | Output JSON to stdout |

### `mikado campaigns`

List available campaigns in your organization.

```bash
mikado campaigns
```

```
  ID        Name              Status    Templates Conversations
  928721aa  Sales Calls       ACTIVE    2         142
  3f8a2b1c  Support Tickets   ACTIVE    1         89
```

### `mikado status <job-id>`

Check the processing status of a submitted transcript.

```bash
mikado status 3f8a2b1c-...
```

```
  Job:      3f8a2b1c-...
  Status:   ✓ SUCCESS
  Duration: 11.2s
  Insights: 1 generated
  Sentiment: positive (0.82)
```

### `mikado result <conversation-id>`

Retrieve full results for a processed conversation.

```bash
mikado result 550e8400-...
```

### `mikado auth`

Set up or update authentication credentials.

```bash
mikado auth
mikado auth --key mkd_... --url https://api.mikado.ai
```

## JSON Output

All commands support `--json` for machine-readable output. Errors go to stderr, data goes to stdout.

```bash
# Pipe to jq
mikado submit transcript.txt --campaign 928721aa --json | jq '.insights[0]'

# Batch processing
for f in transcripts/*.txt; do
  mikado submit "$f" --campaign 928721aa --json >> results.jsonl
done
```

## Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | General error (auth failure, network error) |
| `2` | Invalid arguments |
| `3` | Processing failed (pipeline error) |
| `4` | Timeout (polling exceeded `--timeout`) |

## MCP Server

Use Mikado AI as a tool in AI agents via the [Model Context Protocol](https://modelcontextprotocol.io/).

### Configuration

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "mikado": {
      "command": "npx",
      "args": ["-y", "-p", "@mikado-ai/cli", "mikado", "mcp"],
      "env": {
        "MIKADO_API_KEY": "mkd_your_api_key",
        "MIKADO_URL": "https://mikadoai.app"
      }
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add mikado -- npx -y -p @mikado-ai/cli mikado mcp
```

### Available Tools

| Tool | Description |
|------|-------------|
| `mikado_submit_and_wait` | Submit a transcript and wait for full results. Primary tool for AI agents. |
| `mikado_submit` | Submit a transcript, return immediately with job ID. |
| `mikado_status` | Check processing status of a job. |
| `mikado_result` | Get results for a completed conversation. |
| `mikado_campaigns` | List available campaigns. |

### Example Agent Workflow

```
1. Call mikado_campaigns to see available campaigns
2. Call mikado_submit_and_wait with transcript + campaign
3. Use the returned insights (scores, labels, extracted data) in your response
```

## Local Development

```bash
cd cli
npm install
npm run build      # Build to dist/
npm run dev        # Watch mode

# Test locally
node dist/index.js --help
node dist/index.js auth --key mkd_... --url http://localhost:8100
```

## Requirements

- Node.js 18 or later
- A [Mikado AI](https://mikadoai.app) account with an API key

## License

MIT