npm package: @monkeyhub/cli
Description: Command-line access to MonkeyHub powered by [`@monkeyhub/sdk`](../typescript).
Latest version: 0.2.1

# `@monkeyhub/cli`

Command-line access to MonkeyHub powered by [`@monkeyhub/sdk`](../typescript).

## Install

```bash
npm install -g @monkeyhub/cli
```

Or run it with `npx`:

```bash
npx @monkeyhub/cli --help
```

The binary name is:

```bash
monkey
```

## Authentication

The CLI resolves credentials in this order:

1. `--api-key` / `--base-url`
2. `MONKEYHUB_API_KEY` / `MONKEYHUB_BASE_URL`
3. Saved local profile
4. SDK default API base URL

Profiles are stored in:

```bash
~/.monkeyhub/config.json
```

Set up a default profile:

```bash
monkey auth login
monkey auth show
```

Or set a profile non-interactively:

```bash
monkey auth set default --api-key mk_live_your_api_key --base-url http://localhost:3010
monkey auth show
```

Common auth commands:

```bash
monkey auth list
monkey auth use staging
monkey auth remove staging
```

## Global Flags

These flags work on executable commands:

```bash
--profile <name>
--api-key <key>
--base-url <url>
--json
```

`--json` prints exact machine-readable output. Without it, the CLI prints human-readable summaries/tables.

## Structured Input

Commands that accept complex payloads use `--input`:

```bash
# Inline JSON
monkey queue push email-sends --input '{"payload":{"to":"ada@monkeyhub.io"}}'

# JSON file
monkey db query users --input @query.json

# stdin
cat payload.json | monkey db save users --input -
```

## Collections

```bash
# List collections
monkey db list

# Save one item
monkey db save users \
  --config '{"key":{"hashKey":"id"},"indexes":["email"]}' \
  --input '{"id":"user_1","email":"ada@monkeyhub.io"}'

# Get one item
monkey db get users user_1

# Query
monkey db query users --input '{"hashKey":"user_1"}'

# Semantic search
monkey db search docs --input '{"text":"deploy the API","topK":5}'

# Remove
monkey db remove users user_1
```

## Queues

```bash
# Push a job
monkey queue push email-sends --input '{"payload":{"to":"ada@monkeyhub.io"}}'

# Get a job
monkey queue get email-sends job_123

# Query jobs
monkey queue query email-sends --input '{"status":"queued","limit":10}'

# Cancel a job
monkey queue cancel email-sends job_123
```

## Buckets

```bash
# Upload a file
monkey bucket put uploads ./logo.png --input '{"visibility":"public","contentType":"image/png"}'

# Get a file URL
monkey bucket url uploads logo.png

# Fetch metadata
monkey bucket meta uploads logo.png

# Query files
monkey bucket query uploads --input '{"ext":"png","limit":20}'

# Remove a file
monkey bucket remove uploads logo.png
```

## Boxes

```bash
# Create and inspect
monkey box create --input '{"name":"runner","image":"default"}'
monkey box list
monkey box get box_123

# Lifecycle
monkey box pause box_123
monkey box resume box_123
monkey box set-idle-timeout box_123 1800
monkey box destroy box_123

# Execute commands
monkey box exec box_123 "npm test"
monkey box exec box_123 "npm test" --input '{"cwd":"/app","timeout":30000}'

# File transfer
monkey box upload box_123 ./local.txt /app/local.txt
monkey box download box_123 /app/output.txt ./output.txt
monkey box download box_123 /app/output.txt -

# URL
monkey box url box_123

# Mounts
monkey box mount add box_123 --input '{"source":"monkeyhub://uploads","target":"/mnt/uploads"}'
monkey box mount list box_123
monkey box mount remove box_123 /mnt/uploads
```

## Exit Codes

- `0`: success
- `1`: SDK/API/runtime failure
- `2`: CLI usage or input/config error