# @attrove/cli

The Attrove command-line interface for hosted MCP installs, CLI auth, and advanced local fallback workflows.

It gives you:

- Hosted MCP install commands for Claude Code, Cursor, and Claude Desktop
- A global Attrove login for SDK, agent, CI, and local stdio fallback flows
- Optional `.env` export for project-local SDK work via `env write`
- Machine-readable setup and health checks for agents and CI

## Quick Start

### Hosted MCP (recommended)

```bash
npx @attrove/cli install claude-code
```

That writes a hosted MCP config pointing at `https://api.attrove.com/mcp`.
Open Claude Code, Cursor, or Claude Desktop and complete OAuth on first use.
No `sk_` secret is embedded into the client config.

Other supported hosted installs:

```bash
npx @attrove/cli install cursor
npx @attrove/cli install claude-desktop
```

Defaults:

- `claude-code` installs to project scope (`.mcp.json`)
- `cursor` installs to user scope
- `claude-desktop` installs to user scope

`--scope project` is only valid for `claude-code`; other clients reject it
with a clear error.

### Advanced Local Fallback

```bash
npx @attrove/cli login
npx @attrove/cli local install claude-code
npx @attrove/cli whoami
```

Use this only if you intentionally want the local stdio server. It reuses globally stored CLI credentials or falls back to embedded `ATTROVE_*` env config.

## Command Model

### `install`

```bash
npx @attrove/cli install claude-code
npx @attrove/cli install cursor
npx @attrove/cli install claude-desktop
npx @attrove/cli install claude-code --scope user
npx @attrove/cli install claude-code --json
```

Writes hosted remote MCP config for supported clients. This is the default onboarding path.

### `local install` / `local uninstall`

```bash
npx @attrove/cli local install [client|--all]
npx @attrove/cli local uninstall [client|--all]
npx @attrove/cli local install claude-code --json
```

Configures or removes the advanced local stdio fallback for supported clients. `login` is required before `local install`.

### `login`

```bash
npx @attrove/cli login
npx @attrove/cli login --force
```

Signs in through a browser flow and stores the authenticated user globally. This is primarily for SDK, agent, CI, and advanced local MCP workflows.

Use `init` only as a backwards-compatible alias:

```bash
npx @attrove/cli init
```

### `whoami`

```bash
npx @attrove/cli whoami
npx @attrove/cli whoami --json
```

Shows:

- Where credentials are coming from (`global` or local `.env`)
- Which profile is active
- Which MCP clients already have Attrove configured

### `connect`

```bash
npx @attrove/cli connect --session <session-id>
npx @attrove/cli connect --session <session-id> --json
npx @attrove/cli connect gmail --token <pit_token> --user-id <user-id>
```

Starts the end-user OAuth handoff from a terminal or agent context. Prefer `--session` for partner-issued durable connect sessions.

### `env write`

```bash
npx @attrove/cli env write
npx @attrove/cli env write ./apps/example --json
```

Writes `ATTROVE_SECRET_KEY` and `ATTROVE_USER_ID` to a project-local `.env`.

### `doctor`

```bash
npx @attrove/cli doctor
npx @attrove/cli doctor --json
```

Checks:

- CLI version
- Credential availability
- Authenticated API connectivity
- Detected MCP client configuration

The command exits with status `1` if any check reports an issue.

### `logout`

```bash
npx @attrove/cli logout
npx @attrove/cli logout --json
```

Removes:

- Global Attrove credentials
- The current project `.env` credentials, if present
- Attrove MCP entries from detected clients

### Legacy `mcp`

```bash
npx @attrove/cli mcp install
```

The legacy `mcp` command now fails fast with migration guidance:

- Use `install <client>` for hosted MCP
- Use `local install` or `local uninstall` for the advanced stdio fallback

## Agent / CI Flow

Create a browser-auth session:

```bash
npx @attrove/cli login --json
```

That prints a single JSON object:

```json
{
  "type": "attrove_cli_setup_session",
  "version": 1,
  "status": "awaiting_browser_auth",
  "sessionId": "...",
  "pollToken": "...",
  "authorizeUrl": "...",
  "expiresAt": "...",
  "pollIntervalMs": 2000
}
```

After the user completes sign-in, resume the session:

```bash
npx @attrove/cli login --json --session-id <id> --poll-token <token>
```

To keep polling until completion:

```bash
npx @attrove/cli login --json --wait --session-id <id> --poll-token <token>
```

On success:

```json
{
  "type": "attrove_cli_setup_status",
  "version": 1,
  "status": "complete",
  "sessionId": "...",
  "expiresAt": "...",
  "completedAt": "...",
  "secretKey": "sk_...",
  "userId": "...",
  "userEmail": "..."
}
```

Machine-readable follow-up commands:

```bash
npx @attrove/cli install claude-code --json
npx @attrove/cli local install claude-code --json
npx @attrove/cli whoami --json
npx @attrove/cli env write --json
npx @attrove/cli doctor --json
npx @attrove/cli logout --json
```

## Global Auth Store

The CLI stores credentials globally and treats that store as the source of truth.
When available, the secret key is stored in the platform credential store:

- macOS: Keychain
- Linux: Secret Service via `secret-tool`
- Windows: DPAPI-protected local secret file

If secure storage is unavailable, the CLI falls back to the metadata file below with restricted permissions.

Default config locations:

- macOS: `~/Library/Application Support/Attrove/config.json`
- Linux: `~/.config/attrove/config.json`
- Windows: `%APPDATA%/Attrove/config.json`

Overrides:

- `ATTROVE_CONFIG_DIR`
- `ATTROVE_PROFILE`

## Supported Clients

Hosted install targets:

- Claude Code
- Cursor
- Claude Desktop

Advanced local fallback targets:

- Claude Code
- Cursor
- Claude Desktop
- Windsurf
- VS Code

## Environment Overrides

- `ATTROVE_API_ORIGIN` or `ATTROVE_BASE_URL`
- `ATTROVE_DASHBOARD_ORIGIN`
- `ATTROVE_CONFIG_DIR`
- `ATTROVE_PROFILE`

## Notes

- Hosted remote MCP is the default path.
- The local stdio server is an advanced fallback.
- The underlying stdio MCP package is [`@attrove/mcp`](https://www.npmjs.com/package/@attrove/mcp).
- For hosted remote MCP details, see [Attrove MCP docs](https://attrove.com/docs/mcp).