> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmaito.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

> Learn the common flags, payload formats, JSON output mode, and command patterns used by the Maito CLI.

The CLI uses named commands. Run `maito help` to print the current command summary.

```sh theme={null}
maito help
```

## Common Flags

| Flag or environment variable | Use                                                              |
| ---------------------------- | ---------------------------------------------------------------- |
| `--json`                     | Print the raw JSON response. Use this for scripts and AI agents. |
| `--api-key <key>`            | Use an API key for one command.                                  |
| `MAITO_API_KEY`              | Use an API key from the current shell.                           |

## JSON Output

Use `--json` whenever another tool needs to parse the response.

```sh theme={null}
maito posts list --limit 10 --json
maito newsletter subscribers list --limit 25 --json
```

## Payloads

Commands that create or update complex resources accept one JSON object from one of these sources:

| Payload source          | Example                                                                             |                                               |
| ----------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------- |
| `--payload-json <json>` | `maito newsletter subscriber-tags create --payload-json '{"name":"Founder Notes"}'` |                                               |
| `--body-json <json>`    | `maito newsletter settings update --body-json '{"publicationName":"Maito Weekly"}'` |                                               |
| `--payload-file <path>` | `maito newsletter issues create --payload-file issue.json`                          |                                               |
| `--body-file <path>`    | `maito billing checkout-session --body-file checkout.json`                          |                                               |
| `--stdin`               | \`cat subscriber.json                                                               | maito newsletter subscribers create --stdin\` |

Only one payload source can be used per command.

## Simple Field Flags

Some commands accept simple flags instead of a JSON payload:

```sh theme={null}
maito posts create --body "Post body" --platform linkedin
maito queue list --status failed --limit 20
```

Where a command supports both simple flags and a payload, the payload replaces the field flags.

## Null Values

Use the string `null` where the CLI supports clearing nullable fields:

```sh theme={null}
maito account-sets set-default-account --account-set-id aset_123 --social-account-id null
```

## Resource Names

Use plural resource names:

```sh theme={null}
maito posts list
maito newsletter subscribers list
```