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

# clients

> Create, list, inspect, and update clients.

Clients are the billed entities in a workspace. Each one owns its projects and its invoice
recipients. For fields and response details, see the
[API reference](/api-reference/clients/get).

<Note>
  A client is addressed by its `identifier`, the short hex string returned by `clients list`
  and `clients show`. The record `id` (a UUID) is what `projects create --client-id` expects.
</Note>

<Note>
  Sample responses on this page show the JSON envelope (`--json`). Pretty output is the
  default on a terminal and its columns adapt to width. See
  [Output formats](/cli/output-formats).
</Note>

## clients list

Find a client's identifier by name or status. Start here when you have a name and need an ID
for another command.

```bash theme={"system"}
neetoinvoice clients list --name acme
```

| Flag       | Type     | Required | Default | Description                          |
| ---------- | -------- | -------- | ------- | ------------------------------------ |
| `--name`   | `string` | No       |         | Filter by name (substring match)     |
| `--status` | `string` | No       |         | Filter by status: active or archived |

```json theme={"system"}
{
  "data": {
    "clients": [
      {
        "id": "3f0c0f87-ddc7-45f4-ad7a-c3690fa04963",
        "identifier": "7c1f5e2a9b",
        "name": "Acme Corp",
        "secondary_name": "Acme Holdings",
        "status": "active",
        "currency": "USD",
        "default_invoice_due_in_days": 30
      }
    ]
  },
  "breadcrumbs": [
    { "label": "Show", "command": "neetoinvoice clients show <client-id>" }
  ]
}
```

## clients show

Show one client together with its invoice recipients.

```bash theme={"system"}
neetoinvoice clients show 7c1f5e2a9b
```

### Required arguments

* `<client-id>` - the client's `identifier`.

```json theme={"system"}
{
  "data": {
    "client": {
      "id": "3f0c0f87-ddc7-45f4-ad7a-c3690fa04963",
      "identifier": "7c1f5e2a9b",
      "name": "Acme Corp",
      "status": "active",
      "currency": "USD"
    },
    "recipients": [
      {
        "id": "128c1dfc-b29f-4fda-9a05-8a90e197b81b",
        "name": "Sam Smith",
        "email": "sam@example.com"
      }
    ]
  },
  "breadcrumbs": [
    {
      "label": "Update",
      "command": "neetoinvoice clients update <client-id> --name <name>"
    },
    {
      "label": "Add recipient",
      "command": "neetoinvoice recipients create --client <client-id> --name <name> --email <email> --user-email <email>"
    }
  ]
}
```

## clients create

Create a client. Only `--name` is required; the rest can be filled in later with
`clients update`.

```bash theme={"system"}
neetoinvoice clients create \
  --name "Acme Corp" \
  --secondary-name "Acme Holdings" \
  --address "1 Market St, San Francisco, CA" \
  --due-in-days 30
```

| Flag               | Type     | Required | Default | Description                 |
| ------------------ | -------- | -------- | ------- | --------------------------- |
| `--address`        | `string` | No       |         | Full address                |
| `--due-in-days`    | `int`    | No       | `0`     | Default invoice due in days |
| `--internal-notes` | `string` | No       |         | Internal notes              |
| `--name`           | `string` | Yes      |         | Client name                 |
| `--secondary-name` | `string` | No       |         | Secondary name              |
| `--status`         | `string` | No       |         | Status (active/archived)    |

```json theme={"system"}
{
  "data": {
    "notice_code": "thumbs_up",
    "client_id": "3f0c0f87-ddc7-45f4-ad7a-c3690fa04963"
  },
  "breadcrumbs": [
    { "label": "Show", "command": "neetoinvoice clients show <client-id>" }
  ]
}
```

With `--quiet` the command prints only the new client's ID, which is convenient for scripting:

```bash theme={"system"}
CLIENT_ID=$(neetoinvoice clients create --name "Acme Corp" --quiet)
```

## clients update

Update a client. Only the flags you pass are changed.

```bash theme={"system"}
neetoinvoice clients update 7c1f5e2a9b --status archived
```

### Required arguments

* `<client-id>` - the client's `identifier`.

| Flag               | Type     | Required | Default | Description                 |
| ------------------ | -------- | -------- | ------- | --------------------------- |
| `--address`        | `string` | No       |         | Full address                |
| `--due-in-days`    | `int`    | No       | `0`     | Default invoice due in days |
| `--internal-notes` | `string` | No       |         | Internal notes              |
| `--name`           | `string` | No       |         | Client name                 |
| `--secondary-name` | `string` | No       |         | Secondary name              |
| `--status`         | `string` | No       |         | Status (active/archived)    |

```json theme={"system"}
{
  "data": { "notice_code": "thumbs_up" },
  "breadcrumbs": [
    { "label": "Show", "command": "neetoinvoice clients show <client-id>" }
  ]
}
```