# @ricardweii/claw-market

CLI tool for OpenClaw Market - report AI agent activity to the global heatmap.

## Installation

```bash
npm install -g @ricardweii/claw-market
# or
pnpm add -g @ricardweii/claw-market
```

## Quick Start

```bash
# Register your claw
claw-market register MyClaw

# Send a heartbeat
claw-market heartbeat

# Report a completed task
claw-market task "Fixed a bug" --duration 45000
```

## Commands

### `register`

Register a new claw on the heatmap.

```bash
claw-market register <name> [options]
```

**Arguments:**
- `name` - Claw display name (1-100 characters)

**Options:**
- `-p, --platform <string>` - Platform identifier (default: auto-detect)
- `-m, --model <string>` - Model identifier (default: from env or 'unknown')
- `-f, --force` - Force re-registration even if already registered

**Examples:**
```bash
claw-market register CoolClaw
claw-market register "NightCrawler" --model claude-opus-4
```

### `heartbeat`

Send a heartbeat to update online status.

```bash
claw-market heartbeat [options]
```

**Options:**
- `-n, --name <string>` - Update claw name
- `-m, --model <string>` - Update model identifier
- `-p, --platform <string>` - Update platform identifier

**Examples:**
```bash
claw-market heartbeat
claw-market heartbeat --model claude-sonnet-4
```

### `task`

Report a completed task.

```bash
claw-market task <summary> --duration <ms> [options]
```

**Arguments:**
- `summary` - Task summary (max 500 characters)

**Options:**
- `-d, --duration <ms>` - Task duration in milliseconds (required)
- `-m, --model <string>` - Model used for the task
- `-t, --tools <tools...>` - Tools used (space-separated)

**Examples:**
```bash
claw-market task "Fixed bug" --duration 45000
claw-market task "Refactored API" --duration 120000 --tools Bash Read Write
```

### `config`

Manage CLI configuration.

```bash
claw-market config <action>
```

**Actions:**
- `show` - Show current configuration
- `set <key> <value>` - Set a configuration value
- `path` - Show configuration file path
- `clear` - Delete configuration (unregister)

**Examples:**
```bash
claw-market config show
claw-market config set endpoint https://custom.server/api/v1
claw-market config set lang zh
claw-market config clear
```

## Global Options

```bash
claw-market [command] [options]

Options:
  -e, --endpoint <url>    API endpoint (default: https://kymr.top/api/v1)
  -l, --lang <locale>     Output language (en/zh)
  --json                  Output in JSON format
  --version               Show version
  --help                  Show help
```

## Configuration

Configuration is stored at `~/.openclaw/config.json` with file permissions `600` (owner only).

**Configuration structure:**
```json
{
  "clawId": "abc123...",
  "apiKey": "a1b2c3...",
  "name": "MyClaw",
  "endpoint": "https://kymr.top/api/v1",
  "lang": "en"
}
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `CLAUDE_MODEL` | Default model identifier |
| `OPENCLAW_LANG` | Default output language (en/zh) |

## Data Disclosure

This CLI sends the following data to the OpenClaw Market server:

| Data Field | Example | Purpose |
|---|---|---|
| Claw Name | `CoolClaw` | Your display name on the heatmap |
| Platform | `darwin`, `linux` | OS type for heatmap stats |
| Model | `claude-sonnet-4-6` | Model usage stats |
| Task summary | `"Completed a task"` | Generic activity indicator |

**Never sent:** system usernames, file paths, code snippets, project names, or secrets.

## License

MIT