> For the complete documentation index, see [llms.txt](https://docs.moderncollections.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.moderncollections.io/clients/cli.md).

# CLI

Use the modern-collections CLI from the terminal. An agent should use the hosted MCP server instead.

Use `modern-collections` to work with placements, documents, and payments from your terminal or scripts.

## Connect

An agent should use the [hosted MCP server](/clients/mcp.md) instead. The command is in the `modern-collections` package (Python 3.11 or later; the PyPI project `mc-api` is unrelated).

```bash
uv tool install modern-collections      # or: pip install modern-collections

export MC_API_ENV=prod
export MC_API_KEY="ca_REPLACE_WITH_YOUR_KEY"

modern-collections whoami
```

`whoami` names the account the key reaches and lists anything that blocks placing (verification, the agreement, the payout account). `health` only checks the host is reachable.

| Variable          | Value                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------ |
| `MC_API_ENV`      | `prod`. There is no default environment                                                    |
| `MC_API_BASE_URL` | An explicit API URL instead, such as the sandbox's `https://api.demo.moderncollections.io` |
| `MC_API_KEY`      | Your key                                                                                   |
| `MC_API_CREDITOR` | For a partner key, the linked creditor to act for                                          |

In PowerShell: `$env:MC_API_ENV = "prod"`.

Partner keys (`pa_…`) also need a linked creditor. List them, then pass one as `--creditor` or set `MC_API_CREDITOR`:

```bash
modern-collections partner creditors
export MC_API_CREDITOR="acme-freight"
modern-collections placements list
```

To select a different creditor for one command, put the global option before the command: `modern-collections --creditor northwind-supply placements list`.

The `partner` commands act across the book and take no `--creditor`:

| Command                                                                         | Does                                                                                       |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `creditors`, `placements`, `export`                                             | Linked creditors, placements across the book, a CSV of placements, remittances or payments |
| `remittances`, `statements`                                                     | Every linked creditor's rows, with totals                                                  |
| `notifications`, `set-notifications`                                            | What you and your creditors hear, per event                                                |
| `import-template`, `import-creditors` (`--dry-run`), `import-status`, `imports` | Bulk creditor import                                                                       |
| `create-creditor`, `submit-kyb`, `invite`, `update-link`, `fulfil-evidence`     | Onboarding                                                                                 |

`modern-collections partner --help` lists them all.

## Upload files

Attach each file to an existing placement. Replace `PLACEMENT_ID` with its UUID:

```bash
modern-collections documents upload ./invoice.pdf --placement PLACEMENT_ID --type invoice
modern-collections documents upload ./contract.pdf --placement PLACEMENT_ID --type contract
modern-collections documents list --placement PLACEMENT_ID
```

Each upload returns a document `id`. Processing runs in the background; inspect its status and extracted facts with:

```bash
modern-collections documents get DOCUMENT_ID
```

`documents process DOCUMENT_ID` processes now; it skips an already processed document unless you add `--force`. `--type` is a type hint; omitting `--placement` asks the platform to match the document to a placement. One file per command; formats and limits are in [Upload files](/rest-api/documents.md).

To let someone else upload a file from their browser, make a short-lived link:

```bash
modern-collections documents upload-link PLACEMENT_ID --type invoice
```

The link works for several files for 30 minutes (`--minutes` sets 1–60) and needs no login, so share it only with the person uploading.

### Create a placement from an invoice

If you need the platform to extract placement details from a PDF or image, start with an intake draft:

```bash
modern-collections intake file ./invoice.pdf
```

Review the returned draft, then confirm it using its `draft_id`:

```bash
modern-collections intake file-confirm DRAFT_ID
```

Check the returned `status` and `placement_id`; a draft can instead need review or be rejected. `--edits '{"field":"value"}'` corrects extracted fields. The source file is added to the placement's documents.

## Use in scripts

Global options go **before** the command. Use `--output json` for machine-readable output:

```bash
modern-collections --output json placements list
modern-collections --output json documents list --placement PLACEMENT_ID
```

To read what changed after a missed webhook, pass `--updated-since` with a timestamp that has a timezone offset; rows come oldest change first. See [Catching up after a missed webhook](/webhooks/receiving.md#catching-up-after-a-missed-webhook).

```bash
modern-collections --output json placements list --updated-since 2026-10-01T12:00:00Z --limit 100
```

Exit codes: `0` success, `1` API or runtime error, `2` configuration or usage error. Reads are retried on `429`, `502`, `503` and `504`. A write is retried only when it carries `--idempotency-key` (`placements create`, `recall`, `amend`, `pause`, `resume`, `unrecall`; `payments record`; `disputes resolve`; `documents upload`; `exports create`; `intake structured`, `csv-preview`, `csv-commit`, `file`, `file-confirm`; `partner create-creditor`, `invite`, `import-creditors`, `import-placements`, `recall-all`).

## Connect an AI assistant

The same package configures Claude Code, Cursor or Claude Desktop for the hosted MCP server, and installs the agent skills:

```bash
modern-collections mcp install --client claude-code      # or cursor, claude-desktop
modern-collections skills install
```

`modern-collections --help` and `modern-collections <command> --help` list the current commands and options. See [MCP](/clients/mcp.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.moderncollections.io/clients/cli.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.