# 03 — The CLI: how to talk to Paperclip from a terminal

Paperclip has a clickable web dashboard (the "board") **and** a command-line tool
(the CLI). Both do the same things. This project uses the CLI a lot because it's
easy to automate, safe to run read-only, and great for learning what each command
does.

## Where the CLI lives

On the 3050, the CLI is installed under your user folder (no admin needed):

```
CLI=/home/mike/.paperclip/cli/current/node_modules/paperclipai/dist/index.js
NODE=/home/mike/.local/node24/bin/node
```

You run commands like this:

```
$NODE $CLI <command> <subcommand>
```

That's long to type every time, so the helpers in this project shorten it for
you. But it's good to know the real shape once.

## The command families

Run a family name alone for its list — e.g. `$NODE $CLI company` prints all
company subcommands. The main groups:

| Family | What it does | Examples |
|---|---|---|
| `doctor` | Check your install is healthy | `doctor` |
| `onboard` | First-run setup (already done for you) | `onboard --yes` |
| `company` | Manage companies | `company list`, `company current`, `company stats`, `company create` |
| `agent` | Manage employees | `agent list`, `agent get <id>`, `agent hire`, `agent pause` |
| `issue` | Work orders | `issue list`, `issue create`, `issue assign` |
| `approval` | Sign-offs | `approval list`, `approval approve <id>` |
| `activity` | What's been happening | `activity` |
| `dashboard` | One-screen summary | `dashboard` |
| `heartbeat` | Regular check-ins | `heartbeat list/get` |
| `budget` / `cost` | Spending | `cost` |
| `project` / `goal` | Grouping work | — |
| `token` | API keys for the board | — |

## Always available

Get help on anything with `--help`:

```
$NODE $CLI approval --help
$NODE $CLI agent hire --help
```

**Rule:** if you're unsure what a command changes, run it with `--help` first.
That costs nothing and tells you exactly what it would do.

## The three read-only commands you can safely type any time

```
$NODE $CLI company current      # what company am I in?
$NODE $CLI agent list           # who are my employees?
$NODE $CLI dashboard            # how is everything?
```

The project's `scripts/status.sh` wraps all of these into one snapshot.

## Try it

Run the status helper (see `docs/01` if you haven't):

```
cd /mnt/datapool/hermes_workspace/projects/paperclip-learning
./scripts/status.sh
```

Now, run **one** raw CLI command yourself to feel it — copy this line:

```
cd /mnt/datapool/hermes_workspace/projects/paperclip-learning && ./scripts/status.sh company
```

Then move to `docs/04-companies-and-agents.md`.
