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.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
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.
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.
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.
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.
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.
--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.
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.
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).
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.
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.
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.
