# Switch Parental Controls

> Reference skill for operating the switch-parental-controls CLI to manage Nintendo Switch parental controls. Use this skill whenever you need to run `switch-parental-controls` commands — checking today's or monthly usage, listing devices, setting playtime limits, adding extra time, configuring bedtime alarms, managing content restrictions, or reviewing player and app data. Trigger for any task involving the switch-parental-controls CLI, even if the user just says "how much did the kids play today", "show me each day this month", or "add 30 minutes for Emma's Switch" — those map directly to CLI commands covered here.

- Skill: `udondan/switch-parental-controls` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add udondan/switch-parental-controls`
- Raw SKILL.md: https://api.skillmd.com/api/skills/udondan/switch-parental-controls/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: udondan (https://skillmd.com/u/udondan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/udondan/switch-parental-controls

---


## Overview

`switch-parental-controls` is a CLI (and MCP server) for managing Nintendo Switch parental controls via the Nintendo Parental Controls API. It can read usage data, set playtime limits, configure bedtime alarms, restrict content, and manage per-app allow lists.

**Binary name:** `switch-parental-controls`

**Install:**

```
pip install switch-parental-controls
```

**Run without installing:**

```
uvx switch-parental-controls <command>
```

## Authentication

**Assume the user is already authenticated.** Every command requires a saved session token, and that token is obtained through a one-time interactive login that a human must complete manually — it cannot be automated. Do not attempt to run `login` yourself.

The token is stored at `~/.config/switch-parental-controls/credentials` by default (or `$XDG_CONFIG_HOME/switch-parental-controls/credentials` if `XDG_CONFIG_HOME` is set), or override with the `SWITCH_PARENTAL_CONTROLS_SESSION_TOKEN` environment variable. If any command fails with "Error: Not authenticated", tell the user to run the following command manually in their own terminal and follow the prompts:

```
switch-parental-controls login
```

The login flow requires opening a Nintendo URL in a browser, completing the sign-in, then copying the redirect URL and pasting it back into the running terminal. Once done, the token is saved automatically and all subsequent commands work without further setup.

**Remove saved credentials:**

```
switch-parental-controls logout
```

## Global Options

These flags apply to every command and must be placed **before the subcommand name**, not after it:

```
# correct
switch-parental-controls --timezone America/New_York today-summary

# wrong — will be rejected
switch-parental-controls today-summary --timezone America/New_York
```

| Flag | Env var | Default | Description |
|------|---------|---------|-------------|
| `-t, --timezone TEXT` | `SWITCH_PARENTAL_CONTROLS_TIMEZONE` | `Europe/London` | IANA timezone (e.g. `America/New_York`) |
| `-l, --lang TEXT` | `SWITCH_PARENTAL_CONTROLS_LANG` | `en-GB` | Language code (e.g. `en-US`) |

Setting the env vars avoids having to repeat the flags on every command.

## Devices vs Players

**Device** — the physical Nintendo Switch console. Device names look like `"Switch #1"` or `"Daniel's Switch"`. This is what the `[DEVICE]` argument refers to throughout the CLI.

**Player** — a Nintendo Account profile linked to a device (a person, e.g. "Emma" or "Max"). Players are not devices. Never pass a person's name as the `[DEVICE]` argument.

If the user says "how long did Emma play today", that is a question about a **player**, not a device. Run `list-players` to get each player's today's playtime by nickname. Use `get-player` if you also need the apps they played. Do not use `today-summary` for per-player questions — it only returns device-level totals (total playing time, disabled time, exceeded time).

For per-player historical data ("how much did Emma play in April?", "show me Emma's daily breakdown"), use `--player <player-id>` on `monthly-summary` or `playtime`. Player IDs can be found via `list-players --format json`.

## Device Resolution

Most commands accept an optional `[DEVICE]` positional argument. `DEVICE` is the console name or ID — never a person's name. If omitted and the account has exactly one device, it is selected automatically.

`DEVICE` accepts either a **device name** (e.g. `"Switch #1"`) or a **device ID** (e.g. `abc123def456`). Names are resolved via a persistent cache at `~/.config/switch-parental-controls/devices` by default (or `$XDG_CONFIG_HOME/switch-parental-controls/devices` if `XDG_CONFIG_HOME` is set).

Every command populates the cache automatically on first use (from the already-initialized API client — no extra network call). The cache persists across sessions, so you do not need to run `list-devices` before every command. Run it explicitly only when you need to confirm current device names or after adding, removing, or renaming a device:

```
switch-parental-controls list-devices
```

## Output Formats

Most commands support `--format markdown|json`. The default is `markdown` (human-readable). Use `--format json` for machine parsing.

```
switch-parental-controls list-devices --format json
```

---

## Command Reference

### Authentication

#### `login` _(human-only, do not run as an agent)_
Interactive OAuth flow that requires a browser and human input. If the user needs to authenticate, instruct them to run this themselves — you cannot complete it on their behalf.

```
switch-parental-controls login
```

#### `logout`
Remove saved credentials from disk.

```
switch-parental-controls logout
```

---

### Device Information

#### `list-devices`
List all Nintendo Switch devices linked to the account. Overwrites the local device name cache — use this when you need to confirm current device names or after adding, removing, or renaming a device.

```
switch-parental-controls list-devices [--format markdown|json]
```

#### `get-device`
Get detailed status for a specific device.

```
switch-parental-controls get-device [DEVICE] [--format markdown|json]
```

#### `today-summary`
Show today's device-level playtime summary (total playing time, disabled time, exceeded time). Does not break down playtime by player — use `list-players` for per-player data.

```
switch-parental-controls today-summary [DEVICE] [--format markdown|json]
```

#### `monthly-summary`
Show a monthly playtime summary with per-player totals. Defaults to the most recent **completed** month — it does not return data for the current in-progress month. Use `playtime` for current-month data.

Past-month responses are cached locally and served from cache on subsequent calls. Pass `--no-cache` to skip cache and always fetch live data.

```
switch-parental-controls monthly-summary [DEVICE] [--year YEAR --month MONTH] [--player PLAYER_ID] [--no-cache] [--format markdown|json]
```

- `--year` and `--month` must be provided together; neither alone is valid.
- `--player PLAYER_ID`: filter to a specific player — shows only that player's total and a per-day breakdown. Use `list-players --format json` to find player IDs.
- `--no-cache`: bypass the local cache (read and write); always hits the Nintendo API.

#### `playtime`
Show per-day playtime for a month. For the **current month**, reads live data from the device's daily summaries feed (includes playing time, disabled time, and exceeded time per day). For **past months**, reads from the monthly summary API (total playtime per day only).

Past-month responses are cached locally. Pass `--no-cache` to skip cache and always fetch live data.

```
switch-parental-controls playtime [DEVICE] [--year YEAR --month MONTH] [--day DAY] [--player PLAYER_ID] [--no-cache] [--format markdown|json]
```

- Omit `--year`/`--month` to get the current month's day-by-day breakdown.
- `--year` and `--month` must be provided together; neither alone is valid.
- `--day DAY`: filter to a single specific day (1–31). Requires `--year` and `--month`. Returns a compact single-day summary instead of the full month — use this when you only need one date (e.g. "how much did they play on the 15th?") to avoid returning a full month of data.
- `--player PLAYER_ID`: filter to a specific player — shows only that player's playtime per day (works for both current and past months). Use `list-players --format json` to find player IDs.
- `--no-cache`: bypass the local cache (read and write); always hits the Nintendo API.
- Use this instead of `monthly-summary` when you need to see which specific days had the most playtime, or to answer "how much did they play on Tuesday the 13th?"

#### `clear-cache`
Delete locally cached historic play data. Without options, clears the entire cache.

```
switch-parental-controls clear-cache [--device DEVICE] [--year YEAR] [--month MONTH]
```

- `--device`: limit to a specific device (name or ID).
- `--year`: limit to a specific year.
- `--month MONTH`: limit to a specific month (requires `--year`).

---

### Playtime Controls

#### `set-playtime-limit`
Set or remove the daily playtime limit.

```
switch-parental-controls set-playtime-limit [DEVICE] --minutes N
switch-parental-controls set-playtime-limit [DEVICE] --no-limit
```

- `--minutes N`: 0–360 minutes
- `--no-limit`: remove the daily limit entirely

#### `add-extra-time`
Add extra playtime for today only (one-time override).

```
switch-parental-controls add-extra-time [DEVICE] MINUTES
```

- `MINUTES`: 1–360

#### `set-timer-mode`
Set whether the playtime limit applies equally every day or can vary per day.

```
switch-parental-controls set-timer-mode [DEVICE] MODE
```

- `MODE`: `DAILY` or `EACH_DAY_OF_THE_WEEK`

#### `set-day-restrictions`
Configure playtime and bedtime rules for a specific day of the week.

```
switch-parental-controls set-day-restrictions [DEVICE] DAY [OPTIONS]
```

**DAY:** `MONDAY` | `TUESDAY` | `WEDNESDAY` | `THURSDAY` | `FRIDAY` | `SATURDAY` | `SUNDAY`

**Playtime options:**

| Flag | Description |
|------|-------------|
| `--playtime-enabled` | Enable playtime limit for this day |
| `--playtime-disabled` | Disable playtime limit for this day |
| `--max-playtime-minutes N` | Max minutes (required when `--playtime-enabled`) |

**Bedtime options:**

| Flag | Description |
|------|-------------|
| `--bedtime-enabled` | Enable bedtime restriction for this day |
| `--bedtime-disabled` | Disable bedtime restriction for this day |
| `--bedtime-alarm-hour H` | Alarm hour, 16–23 (required when `--bedtime-enabled`) |
| `--bedtime-alarm-minute M` | Alarm minute, 0–59 (default: 0) |
| `--bedtime-end-hour H` | End hour, 5–9 (required when `--bedtime-enabled`) |
| `--bedtime-end-minute M` | End minute, 0–59 (default: 0) |

---

### Restriction Controls

#### `set-restriction-mode`
Set what happens when the playtime limit is reached.

```
switch-parental-controls set-restriction-mode [DEVICE] MODE
```

- `MODE`: `FORCED_TERMINATION` (game stops) or `ALARM` (alarm sounds but play continues)

#### `set-content-restriction`
Set the age-based content restriction level.

```
switch-parental-controls set-content-restriction [DEVICE] LEVEL
```

- `LEVEL`: `NONE` | `CHILDREN` | `YOUNG_TEENS` | `OLDER_TEENS` | `CUSTOM`

#### `set-bedtime-alarm`
Set the bedtime alarm time (the hour the Switch locks for the night).

```
switch-parental-controls set-bedtime-alarm [DEVICE] HOUR MINUTE
```

- `HOUR`: 16–23
- `MINUTE`: 0–59
- Use `0 0` to **disable** the bedtime alarm.

#### `set-bedtime-end`
Set the time the Switch unlocks in the morning.

```
switch-parental-controls set-bedtime-end [DEVICE] HOUR MINUTE
```

- `HOUR`: 5–9
- `MINUTE`: 0–59
- Use `0 0` to **disable** the bedtime end time.

---

### Player Management

#### `list-players`
List all players (Nintendo Account profiles) registered on a device.

```
switch-parental-controls list-players [DEVICE] [--format markdown|json]
```

#### `get-player`
Get details for a specific player.

```
switch-parental-controls get-player [DEVICE] PLAYER_ID [--format markdown|json]
```

---

### Application Management

#### `list-applications`
List all applications (games) on a device with **today's** playtime and each app's allow-list status. This is not a historical report — it shows only today's usage. For monthly game data, use `monthly-summary --format json` (the raw JSON payload contains per-player data; per-application totals are not separately exposed via CLI).

```
switch-parental-controls list-applications [DEVICE] [--format markdown|json]
```

#### `set-app-allow-list`
Add or remove an application from the content restriction allow list. Allow-listed apps can bypass the age-based content restriction and launch regardless of the device's restriction level. Apps not on the allow list remain subject to normal restrictions — they can still launch if their rating is permitted by the active restriction level.

```
switch-parental-controls set-app-allow-list [DEVICE] APP_ID --allow
switch-parental-controls set-app-allow-list [DEVICE] APP_ID --no-allow
```

---

## Common Workflows

### Check today's device-level playtime

Returns total playing time, disabled time, and exceeded time for the device (not per player):

```
switch-parental-controls today-summary
```

### Check today's playtime by player

```
switch-parental-controls list-players
```

### Check how long a specific person played today

Person names ("Emma", "Max") are **players**, not devices. Use `list-players` — it shows each player's today's playtime by nickname. Do not pass the name as `[DEVICE]`:

```
switch-parental-controls list-players
```

For the apps a specific player ran today, use `get-player` with their player ID (visible in `list-players --format json`). For per-day playtime over a full month, use `playtime --player <player-id>`.

> **Note:** If any command returns "Error: Not authenticated", the user needs to run `switch-parental-controls login` manually — this is an interactive step that cannot be automated.

### Check how much was played each day this month

```
switch-parental-controls playtime
```

### Check per-day playtime for a past month

```
switch-parental-controls playtime --year 2025 --month 4
```

### Check playtime for a specific day

```
switch-parental-controls playtime --year 2025 --month 4 --day 15
switch-parental-controls playtime --year 2025 --month 4 --day 15 --player <player-id>
```

### Check how much a specific player played each day this month

First get the player ID, then filter the daily breakdown:

```
switch-parental-controls list-players --format json
switch-parental-controls playtime --player <player-id>
```

### Check how much a specific player played each day in a past month

```
switch-parental-controls playtime --year 2025 --month 4 --player <player-id>
```

### Check how much a specific player played in April 2025 (monthly total + daily breakdown)

```
switch-parental-controls monthly-summary --year 2025 --month 4 --player <player-id>
```

### Check how much was played in April 2025 (all-player totals)

```
switch-parental-controls monthly-summary --year 2025 --month 4
```

### Set a 90-minute daily limit

```
switch-parental-controls set-playtime-limit --minutes 90
```

### Add 30 extra minutes today

```
switch-parental-controls add-extra-time 30
```

### Remove the daily limit entirely

```
switch-parental-controls set-playtime-limit --no-limit
```

### Set a 9 PM bedtime, unlocks at 7 AM

```
switch-parental-controls set-bedtime-alarm 21 0
switch-parental-controls set-bedtime-end 7 0
```

### Disable bedtime alarm

```
switch-parental-controls set-bedtime-alarm 0 0
switch-parental-controls set-bedtime-end 0 0
```

### Set per-day rules (weekdays 1h, weekends 2h)

```
switch-parental-controls set-timer-mode EACH_DAY_OF_THE_WEEK
switch-parental-controls set-day-restrictions MONDAY --playtime-enabled --max-playtime-minutes 60 --bedtime-disabled
switch-parental-controls set-day-restrictions TUESDAY --playtime-enabled --max-playtime-minutes 60 --bedtime-disabled
switch-parental-controls set-day-restrictions WEDNESDAY --playtime-enabled --max-playtime-minutes 60 --bedtime-disabled
switch-parental-controls set-day-restrictions THURSDAY --playtime-enabled --max-playtime-minutes 60 --bedtime-disabled
switch-parental-controls set-day-restrictions FRIDAY --playtime-enabled --max-playtime-minutes 60 --bedtime-disabled
switch-parental-controls set-day-restrictions SATURDAY --playtime-enabled --max-playtime-minutes 120 --bedtime-disabled
switch-parental-controls set-day-restrictions SUNDAY --playtime-enabled --max-playtime-minutes 120 --bedtime-disabled
```

### Restrict content to children's titles, allow a specific game

```
switch-parental-controls set-content-restriction CHILDREN
switch-parental-controls list-applications --format json   # find APP_ID
switch-parental-controls set-app-allow-list <APP_ID> --allow
```

### Work with a specific device by name

```
switch-parental-controls today-summary "Switch #2"
switch-parental-controls set-playtime-limit "Switch #2" --minutes 60
```

---

## Constraints & Gotchas

- **Playtime minutes:** 0–360 for limits; 1–360 for extra time.
- **Bedtime alarm hour:** 16–23 (4 PM – 11 PM). Use `0 0` to disable.
- **Bedtime end hour:** 5–9 (5 AM – 9 AM). Use `0 0` to disable.
- **`set-day-restrictions`** always requires both `--playtime-enabled/--playtime-disabled` AND `--bedtime-enabled/--bedtime-disabled` — both flags are required on every call.
- With `--playtime-enabled`, `--max-playtime-minutes` is required; it must not be set with `--playtime-disabled`.
- With `--bedtime-enabled`, both `--bedtime-alarm-hour` and `--bedtime-end-hour` are required; with `--bedtime-disabled`, none of the bedtime value flags may be set (including non-zero minute values).
- **`monthly-summary`** `--year` and `--month` must be provided together. Does not cover the current in-progress month — use `playtime` for that.
- **`playtime`** `--year` and `--month` must be provided together. Omit both for the current month. `--day` requires `--year` and `--month`.
- **Device name cache** persists across sessions at `~/.config/switch-parental-controls/devices` (or `$XDG_CONFIG_HOME/switch-parental-controls/devices` if `XDG_CONFIG_HOME` is set). Any command populates it automatically on first use if it is missing — no need to run `list-devices` upfront.
- **Auto-select** only works when the account has exactly one device. With multiple devices, always pass `[DEVICE]` explicitly.
- **Content restriction allow list** only matters when a restriction level other than `NONE` is active.
- **Historic data cache** stores raw API responses for past months at `~/.config/switch-parental-controls/cache/{device-id}/{YYYY}-{MM}.json`. The cache is only consulted when `--year` and `--month` are provided explicitly and the month is not the current calendar month. Use `--no-cache` on `monthly-summary`/`playtime` if data looks unexpectedly stale, or run `clear-cache` to remove cached files. The `switch_clear_cache` MCP tool does the same from the MCP side.