> ## 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.

# monthly-ptos

> Read the monthly PTO report and set PTO earned.

The monthly PTO report tracks, per user and per month, the hours expected, the hours worked,
the PTO earned and used, the balance carried from the previous month, and any resulting salary
deduction.

<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>

## monthly-ptos list

Read the report for a month. Omit `--user-email` for the whole organization.

```bash theme={"system"}
neetoinvoice monthly-ptos list --month 7 --year 2026
```

| Flag           | Type     | Required | Default | Description                      |
| -------------- | -------- | -------- | ------- | -------------------------------- |
| `--month`      | `int`    | Yes      | `0`     | Month number (1-12)              |
| `--user-email` | `string` | No       |         | Filter to a single user by email |
| `--year`       | `int`    | Yes      | `0`     | Year, e.g. 2026                  |

```json theme={"system"}
{
  "data": {
    "month": 7,
    "year": 2026,
    "monthly_ptos": [
      {
        "user_email": "oliver@example.com",
        "user_name": "Oliver Smith",
        "expected_hours": 176.0,
        "hours_worked": 168.0,
        "pto_earned": 8.0,
        "pto_used": 8.0,
        "previous_month_pto": 4.0,
        "net_pto": 4.0,
        "salary_deduction": 0.0,
        "locked": false
      }
    ]
  }
}
```

## monthly-ptos update-earned

Set PTO earned for one or more users in a month. `--email` is repeatable. Pass
`--pto-earned 0`, or omit the flag, to clear earned PTO.

```bash theme={"system"}
neetoinvoice monthly-ptos update-earned \
  --month 7 \
  --year 2026 \
  --email oliver@example.com \
  --email sam@example.com \
  --pto-earned 8
```

| Flag           | Type          | Required | Default | Description                          |
| -------------- | ------------- | -------- | ------- | ------------------------------------ |
| `--email`      | `stringSlice` | Yes      | `[]`    | User email (repeatable)              |
| `--month`      | `int`         | Yes      | `0`     | Month number (1-12)                  |
| `--pto-earned` | `float64`     | No       | `0`     | New PTO earned in hours (default: 0) |
| `--year`       | `int`         | Yes      | `0`     | Year, e.g. 2026                      |

The response reports each email separately, so a bad address in the list does not fail the
whole run.

```json theme={"system"}
{
  "data": {
    "month": 7,
    "year": 2026,
    "updated": [
      { "user_email": "oliver@example.com", "pto_earned": 8.0, "net_pto": 4.0 }
    ],
    "skipped": [{ "user_email": "sam@example.com", "reason": "User not found" }]
  }
}
```

<Note>
  Reading the report and changing it are separate permissions. An account that can view
  monthly PTO may still be refused `update-earned`.
</Note>