npm package: @mitsein-ai/cli
Description: Mitsein CLI — dev tooling, API helpers, and workflow automation
Latest version: 0.1.6

# @mitsein-ai/cli

Mitsein CLI — internal dev tool for agent verification and workflow automation.

TypeScript rewrite of `backend/apps/mitsein-cli/` (Python), ported to the Bun monorepo.

## Install

```bash
# From npm (once published)
bunx @mitsein-ai/cli --help

# From monorepo
cd bun-workspace/apps/mitsein-cli
bun install
bun run src/index.ts --help
```

## Quick Start

```bash
# Check backend health
mitsein dev health

# Print dev token
mitsein dev token

# List threads
mitsein thread list

# Send a message and stream the agent run
mitsein thread send <thread_id> "Hello" --stream

# Auto-generated API commands from OpenAPI
mitsein api list-tags
mitsein api list-ops threads
mitsein api threads list-threads

# Login
mitsein auth login
mitsein auth login --device-code
mitsein auth whoami
```

## Commands

| Command | Description |
|---------|-------------|
| `mitsein version` | Print CLI version |
| `mitsein dev health` | Check backend health (`GET /health`) |
| `mitsein dev token` | Print resolved dev token |
| `mitsein dev openapi` | Load and cache OpenAPI spec |
| `mitsein api list-tags` | List available API tags |
| `mitsein api list-ops <tag>` | List operations for a tag |
| `mitsein api <tag> <operation>` | Execute an API operation |
| `mitsein thread list` | List threads |
| `mitsein thread get <id>` | Get thread details |
| `mitsein thread create` | Create a new thread |
| `mitsein thread history <id>` | Show message history |
| `mitsein thread send <id> <msg>` | Send message + start agent run |
| `mitsein run list <thread_id>` | List agent runs |
| `mitsein run get <run_id>` | Get run status |
| `mitsein run tail <run_id>` | Stream events (like `tail -f`) |
| `mitsein run wait <run_id>` | Block until run completes |
| `mitsein run cancel <run_id>` | Cancel a running agent |
| `mitsein messages list <id>` | List messages (no agent) |
| `mitsein messages send <id> <msg>` | Add message (no agent) |
| `mitsein agent invoke <id> <prompt>` | Message + agent start |
| `mitsein project list` | List projects |
| `mitsein project get <id>` | Get project details |
| `mitsein project delete <id>` | Delete a project |
| `mitsein auth login` | Browser or device-code login |
| `mitsein auth logout` | Remove saved credentials |
| `mitsein auth whoami` | Show current identity |

## Global Flags

| Flag | Description |
|------|-------------|
| `--endpoint <url>` | API base URL (default: `http://localhost:8000`) |
| `--token <token>` | Bearer token |
| `--profile <name>` | Profile name (default: `e2e`) |
| `--real` | Use real account for dev token |
| `--json` | Machine-readable JSON output |
| `--debug` | Log HTTP details to stderr |
| `--timeout <sec>` | HTTP timeout (0 = no timeout, default: `30`) |

## Architecture

### Credential Provider Chain

Same 4-step chain as the Python CLI:

1. **ExplicitFlagProvider** — `--token` / `--endpoint`
2. **EnvProvider** — `MITSEIN_TOKEN` / `MITSEIN_API_URL`
3. **OAuthProvider** — `~/.mitsein/oauth/<profile>.json`
4. **DevTokenProvider** — `scripts/dev-token.sh` (localhost only)

### Thread Send Modes

```bash
# Fire-and-forget (default)
mitsein thread send <id> "msg"

# Wait for completion
mitsein thread send <id> "msg" --wait

# Stream events in real-time
mitsein thread send <id> "msg" --stream
```

### OpenAPI Auto-Commands

The `api` command dynamically generates subcommands from the backend's OpenAPI spec:

```bash
mitsein api list-tags                    # See available tags
mitsein api threads list-threads         # Auto-generated from spec
mitsein api threads list-threads --body '{"limit": 10}'
mitsein api threads list-threads --body @payload.json
echo '{}' | mitsein api threads list-threads --body-stdin
```

## Development

```bash
bun run typecheck   # TypeScript check
bun test            # Run tests (43 tests)
bun run build       # Build single binary
```

## Migration Status

| Phase | Content | Status |
|-------|---------|--------|
| P1 | Project skeleton + core layer | ✅ Done |
| P2 | Extended core + API auto commands | ✅ Done |
| P3 | Thread + run + messages commands | ✅ Done |
| P4 | Agent + project + auth commands | ✅ Done |
| P5 | npm publish + docs | ✅ Done |

RFC: [II95V6](https://gitee.com/mitsein/mitsein/issues/II95V6)