# Command-line client

> Documentation index for AI agents: https://angelwood.io/docs/llms.txt

`angelwood-cli` is the REST API from a terminal: list your clients, projects, tasks and invoices, and create clients and tasks. It needs Node.js 20 or later and has no dependencies.

- **Source:** [github.com/NewOdysseyConsulting/angelwood-cli](https://github.com/NewOdysseyConsulting/angelwood-cli)

## Install

```bash
npm install -g github:NewOdysseyConsulting/angelwood-cli
```

This installs it straight from the source repository.

## Sign in

Create an API key in Angelwood under **Settings**, then run:

```bash
angelwood login
```

The key is checked with Angelwood before it is saved to `~/.config/angelwood/config.json`, which only you can read. In scripts and CI, set the `ANGELWOOD_API_KEY` environment variable instead.

## Commands

| Command | What it does |
| --- | --- |
| `angelwood whoami` | Shows the organization and user the key belongs to |
| `angelwood clients list` | Lists clients. Option: `--search` |
| `angelwood clients get <id>` | Shows one client |
| `angelwood clients create --name <name>` | Creates a client. Options: `--email`, `--phone`, `--address` |
| `angelwood projects list` | Lists projects. Options: `--client`, `--status` |
| `angelwood tasks list` | Lists tasks. Options: `--project`, `--status` |
| `angelwood tasks create --project <id> --title <title>` | Creates a task. Options: `--description`, `--priority`, `--due` |
| `angelwood invoices list` | Lists invoices. Options: `--client`, `--project`, `--status` |
| `angelwood logout` | Removes the saved key |

Every list command also takes `--limit` (1 to 100, default 25), `--offset` and `--json`.

## Examples

```bash
# Which invoices are overdue?
angelwood invoices list --status overdue

# Add a task to project 42, due at the end of the year
angelwood tasks create --project 42 --title "Send the Q4 report" --priority high --due 2026-12-31

# Total outstanding balance on sent invoices, with jq
angelwood invoices list --status sent --limit 100 --json | jq '[.data[].balance_due] | add'
```

## Notes

- Creating clients and tasks needs a key with write permission.
- Nothing can be updated or deleted from the command line.
- The limit is 120 API requests per minute per organization.