anton

# Anton CLI Reference ## Invocation ```bash anton <command> [options] ``` The `anton` CLI should be installed globally for best performance — `npx` adds noticeable latency when running many commands per session: ```bash npm install -g @udondan/anton ``` If the `anton` command is not found, suggest the global install above. As a one-off fallback without installing, `npx @udondan/anton <command>` works but is slower. All output is JSON printed to stdout — pipe to `jq` to filter or extract fields: ```bash # Pretty-print (default behaviour) anton weekly Lea | jq . # Extract a single field anton weekly Lea | jq '.totalLevels' # Filter completed levels by subject anton progress Lea | jq '.completedLevels[] | select(.puid | startswith("c-mat"))' # List topic titles with their indices anton topics c-mat-4 | jq '.topics[] | {index: .index, title: .title}' # Get just block titles for a topic anton blocks c-mat-4 --topic-index 6 | jq '.blocks[] | .title' ``` --- ## Authentication Set credentials via a config file **or** environment variables — env vars take precedence. ### Config file Store credentials permanently in `~/.config/anton/config` (mode `0600`): ``` # ~/.config/anton/config ANTON_LOGIN_CODE=ABCD-1234 ANTON_GROUP=Family ``` Lines starting with `#` are comments. ### Environment variables Set at least one of these before running any command: | Variable | Required | Purpose | | ------------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `ANTON_LOGIN_CODE` | one of these two | 8-character parent login code | | `ANTON_LOG_ID` | one of these two | Alternative: parent log ID (starts with `L-`) | | `ANTON_GROUP` | optional | Default group name when parent belongs to multiple groups. Matched case-insensitively. Falls back to the first group when unset. | | `ANTON_ASSIGNMENTS_FILE` | optional | Path to local assignments JSON (default: `~/.config/anton/assignments.json`) | | `ANTON_NO_SESSION_CACHE` | optional | Set to `1` to always bypass session cache (same as `--no-cache`) | ```bash export ANTON_LOGIN_CODE='ABCD-1234' anton status ``` If auth fails after a long session or you see `401`/`unauthorized` errors, the cached session may be stale — rerun with `--no-cache` to force a fresh login. --- ## Global Flags These apply to every command and must come **before** the subcommand: | Flag | Description | | ---------------- | --------------------------------------------------------------- | | `--group <name>` | Override the active group (takes precedence over `ANTON_GROUP`) | | `--no-cache` | Skip the session cache and perform a full login | | `--version` | Print the package version | | `--help` | Print help | ```bash anton --group "Family B" progress Lea anton --no-cache status ``` `--group` selects which family group to operate on — it is not the child name. Omit it when the parent belongs to only one group. --- ## Commands ### Account & Group Info #### `status` Show authentication status, all groups the parent belongs to, and children in the active group. ```bash anton status ``` #### `groups` List all groups the parent account belongs to, with their full member lists. ```bash anton groups ``` #### `group` Show family group details and currently pinned blocks. ```bash anton group ``` #### `children` List children in the active group. ```bash anton children ``` --- ### Pinned Assignments #### `pins` List lesson blocks currently pinned (assigned) to the group. | Option | Description | | ---------------- | --------------------------------------------------------------------- | | `--week <date>` | Filter to a specific week start date (`YYYY-MM-DD`, must be a Monday) | | `--child <name>` | Filter to a specific child by display name | ```bash anton pins anton pins --week 2025-06-16 anton pins --child Lea ``` > **Note:** `anton pins` may return `null` for block titles and block puids when querying future weeks. If you need the puid after pinning, use the `blockPuid` from the `pin` command's response directly — don't rely on a follow-up `pins` call to retrieve it. #### `pin <project>` Assign a lesson block to the group or a specific child. | Option | Description | | ----------------------- | ------------------------------------------------------------ | | `--topic-index <n>` | Topic index (0-based) — get from `anton topics <project>` | | `--topic-title <title>` | Partial topic title match (case-insensitive) | | `--block-index <n>` | Block index (0-based) within the topic | | `--block-title <title>` | Partial block title match (case-insensitive) | | `--week <date>` | Week start date (`YYYY-MM-DD` Monday, default: current week) | | `--child <name>` | Child name to assign to (default: whole group) | Identify the block with either `--topic-index` or `--topic-title`, and either `--block-index` or `--block-title`. Get topic/block indices from `anton topics` and `anton blocks`. > **Warning:** `--block-title` (and `--block-index`) always require a topic selector (`--topic-index` or `--topic-title`). The CLI will error if you omit the topic. Always specify the topic first. ```bash # Assign to whole group by topic index + block index anton pin c-mat-4 --topic-index 6 --block-index 1 # Assign to one child by title match anton pin c-mat-4 --topic-title "Brüche" --block-title "Brüche zuordnen" --child Lea # Assign to a specific week anton pin c-mat-4 --topic-index 6 --block-index 0 --week 2025-06-23 ``` #### `unpin <blockPuid> <weekStartAt>` Remove a pinned block. `blockPuid` is the block's puid (e.g. `c-mat-4/ro9ajj`), `weekStartAt` is the Monday date string. | Option | Description | | ----------------------- | --------------------------------------------------------- | | `--child-id <publicId>` | Child's publicId to disambiguate when multiple pins exist | ```bash anton unpin c-mat-4/ro9ajj 2025-06-16 ``` --- ### Lesson Catalogue #### `plans` Browse the Anton lesson catalogue (~285 courses). | Option | Description | | ----------------------- | ---------------------------------------------------- | | `-s, --subject <code>` | Filter by subject code (e.g. `mat`, `natdeu`, `eng`) | | `-g, --grade <n>` | Filter by grade (1–13) | | `-l, --language <lang>` | Filter by language (default: `de`) | ```bash anton plans anton plans --subject mat --grade 4 anton plans -s eng -g 3 ``` #### `topics <project>` List topics (chapters) for a course. Use this before `blocks` or `pin` to find the right topic index. ```bash anton topics c-mat-4 ``` #### `blocks <project>` List blocks (and their levels) for a single topic within a course. | Option | Description | | ----------------------- | -------------------------------------------- | | `--topic-index <n>` | Topic index (0-based) | | `--topic-title <title>` | Partial topic title match (case-insensitive) | ```bash anton blocks c-mat-4 --topic-index 6 anton blocks c-mat-4 --topic-title "Brüche" ``` #### `plan <project>` Full topic → block → level hierarchy for a course. Can be a large response — prefer `topics` + `blocks` for targeted lookups. ```bash anton plan c-mat-4 ``` #### `lesson <fileId>` Fetch lesson content (questions, trainers) by file ID. ```bash anton lesson list/plans ``` --- ### Child Progress & Activity #### `progress <child>` Learning progress summary for a child — counts, stars, accuracy by subject. | Option | Description | | ---------------- | ------------------------------------------- | | `--since <date>` | Start date `YYYY-MM-DD` (default: all time) | ```bash anton progress Lea anton progress Lea --since 2025-06-01 ``` #### `events <child>` Raw event log for a child (e.g. `finishLevel`, `startLevel`). | Option | Description |