Skill: yujun-bo2/tronclass-cli (version 1.2.2)

--- name: tronclass-cli description: Interact with the TronClass learning management system (currently optimized for FJU) via the `tronclass` CLI — check courses, assignments, deadlines, grades, announcements, and course materials; download lecture slides or PDFs; submit homework. Use whenever the user asks anything about TronClass, even if they don't say "TronClass" explicitly. Triggers include checking what homework is due, downloading lecture slides or PDFs, submitting assignments, listing enrolled courses, reading school or course announcements, or viewing activity details. If the user mentions school, assignments, due dates, course files, or anything that sounds like an LMS task, lean toward using this skill. license: MIT metadata: authors: YuJun-BO2 cli-version: 0.4.0 repository: https://github.com/YuJun-BO2/tronclass-cli-skill homepage: https://github.com/YuJun-BO2/tronclass-cli-ts openclaw: emoji: "🎓" homepage: https://github.com/YuJun-BO2/tronclass-cli-skill requires: bins: - tronclass install: - id: npm kind: node package: tronclass-cli bins: - tronclass label: Install TronClass CLI (npm) --- # TronClass CLI Skill You have access to `tronclass-cli`, a command-line tool for managing the user's TronClass account. ## Setup Install globally (once): ```bash npm install -g tronclass-cli ``` ## General Guidelines - **Authentication**: Most commands require a saved session. If a command fails, tell the user to run `tronclass auth login <username>`. The session is reused automatically; `tronclass auth check` probes a live TronClass endpoint to confirm whether it's still valid. - **FJU users**: Use `tronclass auth login --fju <student_id>` for the CAS flow with CAPTCHA support. - **Non-interactive login (agents/scripts)**: Pass `--password <p>` (and `--base-url <u>` for generic deployments) to skip prompts. For FJU, where a human must solve the CAPTCHA, use the two-step deferred flow: `tronclass auth login --fju --non-interactive <user>` prints a captcha ID and opens the captcha image; then `tronclass auth captcha --password <p> <captcha_id> <code>` completes the login. The password is never written to disk — it is supplied only at resume time. - **Finding IDs**: The typical lookup chain is `courses list` → `activities list <course_id>` → `activities view <activity_id>`. The `todo` command shows activity IDs directly in the first column. - **Aliases**: `activities` → `a`, `courses` → `c`, `homework` → `hw`/`h`, `todo` → `td`/`t`, `announcements` → `ann`. Subcommands also have short aliases (`list`→`l`/`ls`, `view`→`v`, `download`→`d`/`dl`, `submit`→`s`). ## Command Quick Reference | Command | What it does | |---|---| | `tronclass auth login [--fju] [--password <p>] [--base-url <u>] <user>` | Log in (interactive by default; `--password` / `--base-url` make it non-interactive) | | `tronclass auth login --fju --non-interactive <user>` | Start a deferred-CAPTCHA FJU login; prints a captcha ID, no password on disk | | `tronclass auth captcha --password <p> <id> <code>` | Complete a deferred FJU login with the solved CAPTCHA | | `tronclass auth check` | Probe a live endpoint to report session validity (Valid / Expired / Unknown) | | `tronclass auth logout` | Clear saved session | | `tronclass todo` | Pending tasks — first column is the activity ID | | `tronclass courses list [--all] [--raw]` | List courses | | `tronclass activities list <course_id>` | List activities in a course | | `tronclass activities view <activity_id>` | Rich view: metadata + description + attachments | | `tronclass activities download <ref_id> [output]` | Download file (defaults to ~/Downloads/) | | `tronclass homework list <course_id>` | List homework for a course | | `tronclass homework view <activity_id>` | Rich view: metadata + prompt + teacher attachments + your own submission/draft | | `tronclass homework submit <activity_id> <files...>` | Submit homework files | | `tronclass ann list [course_id]` | List announcements (school-wide if no course_id) | | `tronclass ann view <ann_id> [course_id]` | Rich view: metadata + HTML-rendered body + attachments | | `tronclass ann download <ref_id> [output]` | Download an announcement attachment | Most list/view commands support `--fields f1,f2,...` to customize displayed columns. ## Key Behaviors **`tronclass todo`** — shows `id, course_name, title, end_time` by default. The `id` column is the activity ID you can pass directly to `activities view`. **`tronclass activities view <id>`** — displays a formatted table (not raw JSON). The Attachments section lists each file with its `ref_id` and a ready-to-run download command. No need to manually dig through JSON. **`tronclass activities download <ref_id>`** — `output_file` is optional. If omitted, the file is saved to `~/Downloads/<filename>` using the server-provided filename. **`tronclass homework view <activity_id>`** — rich layout: metadata (status / deadline color-coded), HTML-rendered prompt, teacher attachments (each with `ref_id` for `activities download`), and a "My Submission" section showing whether you've submitted, saved a draft, or done nothing — plus the files you uploaded. Use this before submitting to read the prompt and confirm a draft. **`tronclass ann list`** — with no argument, lists the school-wide announcement feed (first page, ~30 items). Pass a `course_id` to list announcements for a specific course. **`tronclass ann view <ann_id>`** — renders the announcement's HTML body in the terminal (bold, links, lists, images). If you know which course the announcement belongs to, pass `course_id` as the second argument to skip a multi-page search of the global feed. ## Common Workflows **Check what's due:** ```bash tronclass todo ``` **Download a course file:** ```bash tronclass courses list # get course_id tronclass activities list <course_id> # get activity_id tronclass activities view <activity_id> # see Attachments table → note ref_id tronclass activities download <ref_id> # saves to ~/Downloads/ automatically ``` **Submit homework:** ```bash tronclass homework list <course_id> # find activity_id tronclass homework view <activity_id> # read the prompt + grab teacher attachments tronclass homework submit <activity_id> ./my_essay.pdf --draft # save a draft first tronclass homework view <activity_id> # verify the draft tronclass homework submit <activity_id> ./my_essay.pdf # final submit ``` **Read announcements:** ```bash tronclass ann list # school-wide feed tronclass ann list <course_id> # course-specific feed tronclass ann view <ann_id> [course_id] # full content, HTML rendered ``` ## Reference Files For detailed option lists, field names, and edge cases, load the relevant reference: - `references/auth.md` — login flows, session management - `references/todo.md` — todo fields, filtering - `references/courses.md` — course fields, `--raw` flag - `references/activities.md` — activities list/view/download in depth - `references/homework.md` — homework list, view, submit options, draft mode - `references/announcements.md` — announcements list, view (HTML rendering), download

path: README.md
content: # TronClass CLI Skill

An Agent Skill that lets an AI agent operate the [TronClass](https://tronclass.com/) learning management system on your behalf, currently optimized for Fu Jen Catholic University (FJU).

Once installed, you can ask your agent in plain language to check assignments, download course files, or submit homework — no more manually clicking through the TronClass web UI.

## Install

### 1. Install the skill

**Via ClawHub CLI** (recommended):

```bash
clawhub install yujun-bo2/tronclass-cli
# or pin a specific version
clawhub install yujun-bo2/tronclass-cli --version 1.0.0
```

The skill page lives at <https://clawhub.ai/yujun-bo2/tronclass-cli>.

**Manual install** (without the ClawHub CLI) — clone into your agent's skills directory:

```bash
git clone https://github.com/YuJun-BO2/tronclass-cli-skill.git \
  ~/.claude/skills/tronclass-cli
```

Adjust the target path for your agent (`.claude/skills/` for project-scoped, `~/.claude/skills/` for personal, or your OpenClaw skills directory).

### 2. Install the underlying CLI

If you installed via ClawHub, OpenClaw will prompt you to install the `tronclass` binary automatically (it's declared in the skill's `metadata.openclaw.install`). Otherwise install it yourself:

```bash
npm install -g tronclass-cli
```

Verify it's on your PATH:

```bash
tronclass --version
```

## First-time login

FJU students (CAS flow with CAPTCHA):

```bash
tronclass auth login --fju <student_id>
```

Other TronClass users:

```bash
tronclass auth login <username>
```

The session is saved locally and reused automatically whenever the agent invokes a command.

## Example prompts

After logging in, just talk to your agent:

- "What assignments do I still need to submit?"
- "Download all the lecture slides from my Data Structures course this semester."
- "Submit ~/Documents/hw3.pdf to homework 3 of Algorithms."
- "List the courses I'm enrolled in this semester."
- "What's due before next Friday?"

The agent will pick the right `tronclass` commands, chain the lookups (courses → activities → download), and summarize the result.

## What this skill provides

This skill gives the agent:

- Purpose, aliases, and fields for every `tronclass-cli` command
- The lookup chain for common workflows (e.g. listing courses before listing activities before downloading a file)
- Detailed reference docs for each subcommand under `references/`

So when you vaguely say "check what's due this week," the agent knows to run `tronclass todo`, knows the first column is the activity ID, and can pipe it straight into `activities view` for details.

## Links

- Skill page: <https://clawhub.ai/yujun-bo2/tronclass-cli>
- Skill repo: <https://github.com/YuJun-BO2/tronclass-cli-skill>
- CLI tool repo: <https://github.com/YuJun-BO2/tronclass-cli-ts>

## License

MIT


path: references/auth.md
content: # Auth Command Reference

## Login

```bash
tronclass auth login [--fju] [--password <p>] [--base-url <u>] <username>
tronclass auth login --fju --non-interactive <username>
```

Login has three modes. The SDK handles CAS / Keycloak automatically.

### 1. Interactive (human users)

```bash
# Generic: prompts for base URL, password, and CAPTCHA (if required)
tronclass auth login <username>

# FJU shortcut: base URL preset to https://elearn2.fju.edu.tw,
# only prompts for password + CAPTCHA
tronclass auth login --fju <student_id>
```

When a CAPTCHA is required, the CLI downloads the image, opens it with the system image viewer, and prompts for input.

### 2. Non-interactive (no CAPTCHA required)

For scripts and deployments that don't serve a CAPTCHA:

```bash
tronclass auth login --password 'my_password' --base-url https://elearn.example.edu.tw <username>
```

### 3. Deferred-CAPTCHA (FJU, for agents)

Two-step flow for agents that cannot solve the CAPTCHA inline. The password is **never persisted** — it is supplied only at resume time.

```bash
# Step 1: parse the form, download the CAPTCHA image, save pending state.
# Exits 0 and prints a captcha ID. No password requested.
tronclass auth login --fju --non-interactive <student_id>

# Step 2: supply the password and the solved CAPTCHA code.
tronclass auth captcha --password '<password>' <captcha_id> <code>
```

Pending state is stored at `~/.tronclass-cli/pending-captcha/<id>.json` (mode `0600`) and expires after **10 minutes**.

### Flags

| Flag | Description |
|---|---|
| `--fju` | Preset base URL to `https://elearn2.fju.edu.tw`. Mutually exclusive with `--base-url`. |
| `--non-interactive` | Defer the CAPTCHA step so the password can be supplied at resume time. **Requires `--fju`**; cannot be combined with `--password` on `auth login`. |
| `--password <p>` | Supply the password non-interactively. For the deferred-CAPTCHA flow, pass it to `auth captcha`, not to `auth login --non-interactive`. |
| `--base-url <u>` | Supply the base URL non-interactively. Mutually exclusive with `--fju`. |

## Captcha

```bash
tronclass auth captcha --password <p> <id> <code>
```

Completes a pending FJU login that was paused on a CAPTCHA challenge.

- `<id>` — the captcha ID printed by `auth login --fju --non-interactive`.
- `<code>` — the characters read from the saved CAPTCHA image.
- `--password <p>` — the user's password (not stored from step 1).

On success, the pending-state file and CAPTCHA image are removed and the session is saved as usual. On failure (wrong code, expired state, network error), the pending state is also cleared (the CAS `execution` token is single-use) — the caller must re-run `auth login --fju --non-interactive` to start over.

```bash
tronclass auth captcha --password 'my_password' abc123def456 3xyz
```

## Check

```bash
tronclass auth check
```

Prints a formatted table with authenticated username, student ID, base URL, school config, and login time, plus a **Status** field driven by a live probe of an authenticated TronClass API endpoint:

| HTTP response | Status |
|---|---|
| `200` | `● Valid` |
| `401` / `403`, or a redirect to the CAS login page | `● Expired` |
| anything else, or network error | `● Unknown` (a `Probe` row is added with the HTTP code or error message) |

The cookie's embedded timestamp is **not** used to estimate expiry — TronClass uses a server-side sliding TTL with semantics the SDK can't read, so any client-side estimate would be misleading. **Login Time** comes from the cookie's creation time and is informational only.

Example output:

```
┌────────────┬─────────────────────────────┐
│ Status     │ ● Valid                     │
│ User       │ 412242266                   │
│ Student ID │ 452378                      │
│ Base URL   │ https://elearn2.fju.edu.tw  │
│ School     │ fju                         │
│ Login Time │ 2026/4/21 03:12:05          │
└────────────┴─────────────────────────────┘
```

## Logout

```bash
tronclass auth logout
```

Clears cookies and config from `~/.tronclass-cli/`.

## Session Storage

All session data lives in `~/.tronclass-cli/`:
- `config.json` — username, studentId, baseUrl, school
- `cookies.json` — session cookies (CookieJar format)
- `pending-captcha/<id>.json` — deferred-login state, mode `0600`, TTL 10 minutes


path: references/announcements.md
content: # Announcements Command Reference

```bash
tronclass ann <subcommand> [options]
```

The `ann` command reads TronClass announcements — both the school-wide feed and per-course announcements. It was added in CLI v0.3.0.

---

## `list [course_id]`

```bash
tronclass ann list [course_id]
tronclass ann l
tronclass ann ls <course_id>
```

Lists announcements as a table with columns: `id`, `title`, `author`, `date`.

| Form | What it shows |
|---|---|
| `tronclass ann list` | School-wide announcement feed (first page, ~30 items) |
| `tronclass ann list <course_id>` | Announcements for that specific course |

Dates are formatted in Taiwan locale. If there are no announcements, the command prints a friendly empty-state message and exits.

---

## `view <ann_id> [course_id]`

```bash
tronclass ann view <ann_id> [course_id]
tronclass ann v <ann_id>
tronclass ann v <ann_id> <course_id>
```

Displays a single announcement as a rich, formatted layout:

1. **Metadata** — title (bold), author, created date, and updated date (shown only if the announcement was edited).
2. **Body** — HTML content rendered directly in the terminal: bold text, hyperlinks (OSC 8 where supported), images, and list formatting are preserved. Not raw HTML and not stripped-to-plaintext — actually rendered.
3. **Attachments** — each file is shown with its `ref_id` and a clickable download link when available. Use the `ref_id` with `ann download`.

**Lookup strategy:**
- With `course_id`: the CLI fetches directly from that course's announcements (fast, exact).
- Without `course_id`: the CLI pages through up to 5 pages of the global feed looking for the ID. If the announcement is older or not in the global feed, pass the `course_id` explicitly.

**Tip:** If `ann view <ann_id>` can't find the announcement, try running `tronclass ann list <course_id>` to confirm the ID, then re-run `ann view` with both arguments.

---

## `download <ref_id> [output]`

```bash
tronclass ann download <ref_id> [output]
tronclass ann d <ref_id>
tronclass ann dl <ref_id> ./notice.pdf
```

Downloads an attachment from an announcement. `ref_id` is shown in the Attachments section of `ann view`. When `output` is omitted, the file is saved to `~/Downloads/<filename>` using the server-provided filename.

---

## Workflow Examples

**Browse latest school-wide announcements and read one:**
```bash
tronclass ann list                       # note the id of interest
tronclass ann view <ann_id>              # full HTML-rendered view
```

**Read a course-specific announcement:**
```bash
tronclass courses list                   # get course_id
tronclass ann list <course_id>           # note the ann_id
tronclass ann view <ann_id> <course_id>  # faster: skips global search
```

**Download an attachment from an announcement:**
```bash
tronclass ann view <ann_id>              # note ref_id in Attachments
tronclass ann download <ref_id>          # saves to ~/Downloads/
```


path: references/activities.md
content: # Activities Command Reference

```bash
tronclass activities <subcommand> [options]
tronclass a <subcommand> [options]
```

---

## `list <course_id>`

```bash
tronclass activities list <course_id> [--fields f1,f2,...]
tronclass a l <course_id>
```

Lists all activities in a course as a table.

**Default fields:** `id, title, type, status, end_time`

| Field | Description |
|---|---|
| `id` | Activity ID |
| `title` | Activity title |
| `type` | Type (homework, material, quiz, …) |
| `status` | Computed: 進行中 / 已結束 / 未開放 |
| `end_time` | End datetime |
| `start_time` | Start datetime |
| `deadline` | Deadline |

---

## `view <activity_id>`

```bash
tronclass activities view <activity_id> [--fields f1,f2,...]
tronclass a v <activity_id>
```

Displays a rich formatted layout:
1. **Metadata table** — id, title (bold), type, status (color-coded), deadline (red if overdue, yellow if within 7 days)
2. **Description** — HTML stripped, word-wrapped to terminal width
3. **Attachments table** — each file shows: `#`, filename (cyan, clickable OSC 8 hyperlink in supported terminals), `ref_id`, size

The Attachments section prints the exact `tronclass a download <ref_id> [output_file]` command for each file — copy-paste ready.

**Default fields:** `id, title, type, data, deadline, uploads`

When `--fields` is specified, shows a plain key-value table instead of the rich layout.

### Finding a ref_id

The `ref_id` shown in the Attachments table is what you pass to `activities download`. Example output:

```
Attachments (2 files)
┌───┬──────────────────────────┬──────────┬─────────┐
│ # │ name                     │ ref_id   │ size    │
├───┼──────────────────────────┼──────────┼─────────┤
│ 0 │ lecture_w3.pdf           │ 28409265 │ 1.4 MB  │
│ 1 │ exercises.pdf            │ 34147059 │ 338 KB  │
└───┴──────────────────────────┴──────────┴─────────┘
```

---

## `download <ref_id> [output_file]`

```bash
tronclass activities download <ref_id> [output_file] [--preview]
tronclass a d <ref_id>
tronclass a dl <ref_id> ./my_file.pdf
```

Downloads a file by its reference ID.

**`output_file` is optional.** When omitted, the filename is taken from the server's `Content-Disposition` header and saved to `~/Downloads/<filename>`.

| Option | Description |
|---|---|
| `output_file` | Local save path (optional; defaults to `~/Downloads/<filename>`) |
| `--preview` | Download preview/compressed version instead of the original |

### Full download workflow

```bash
# 1. Find course ID
tronclass courses list

# 2. Find activity ID
tronclass activities list <course_id>

# 3. View activity — note the ref_id in Attachments
tronclass activities view <activity_id>

# 4. Download (output defaults to ~/Downloads/)
tronclass activities download <ref_id>

# 4b. Or specify a path
tronclass activities download <ref_id> ./downloads/file.pdf
```


path: references/todo.md
content: # Todo Command Reference

```bash
tronclass todo [--fields f1,f2,...]
tronclass td   [--fields f1,f2,...]
tronclass t    [--fields f1,f2,...]
```

Displays the user's current to-do list as a table.

## Default Fields

`id, course_name, title, end_time`

The `id` column is the **activity ID** — use it directly with `tronclass activities view <id>` or `tronclass activities download`.

## Available Fields

| Field | Description |
|---|---|
| `id` | Activity ID (use with `activities view`) |
| `title` | Task title |
| `course_name` | Name of the course |
| `course_id` | Course ID |
| `type` | Activity type (homework, quiz, etc.) |
| `end_time` / `due_at` | Deadline |
| `status` | Completion status |

## Examples

```bash
# Default view (id + course + title + deadline)
tronclass todo

# Show only title and deadline
tronclass todo --fields title,end_time

# Show course ID too
tronclass todo --fields id,course_id,course_name,title,end_time
```


path: references/homework.md
content: # Homework Command Reference

```bash
tronclass homework <subcommand> [options]
tronclass hw <subcommand>
tronclass h  <subcommand>
```

---

## `list <course_id>`

```bash
tronclass homework list <course_id> [--fields f1,f2,...]
tronclass hw l <course_id>
```

Lists all homework activities for a course.

**Default fields:** `id, title, deadline, status, score`

| Field | Description |
|---|---|
| `id` | Activity ID |
| `title` | Homework title |
| `deadline` / `due_at` | Submission deadline |
| `status` | Computed: 已繳交 / 草稿 / 待繳交 / 未繳 |
| `score` | Score received (if graded) |
| `max_score` | Maximum possible score |

---

## `view <activity_id>`

```bash
tronclass homework view <activity_id> [--raw]
tronclass hw v <activity_id>
```

Rich layout for a single homework. Sections:

1. **Metadata table** — id, title, type, status (`已繳交` / `草稿` / `未繳` / `待繳交`, color-coded), deadline (red if overdue, yellow if within 7 days), score if graded.
2. **Description** — assignment prompt with HTML rendered inline (bold, lists, hyperlinks).
3. **Attachments** — teacher-provided files. Each row shows `ref_id` and a clickable OSC 8 hyperlink. Pass the `ref_id` to `tronclass activities download` to save locally.
4. **My Submission** — your own state:
   - `已繳交` (submitted) → submission time, score and instructor feedback if graded, your comment, and `Submitted Files` with download URLs.
   - `草稿` (draft saved) → `Draft Files` with download URLs so you can verify what's queued before finalizing.
   - `(尚未繳交也未儲存草稿)` → nothing submitted yet.

| Option | Description |
|---|---|
| `--raw` | Print the raw JSON from each underlying endpoint (activity body, homework list match, submission list, resolved `user_id`). Useful for debugging tenants where the rendered output looks wrong. |

### Typical use

```bash
# Read the prompt and grab teacher attachments before starting
tronclass homework view 987654

# Save a draft, then view to confirm what's queued
tronclass homework submit 987654 ./essay.pdf --draft
tronclass homework view 987654
```

---

## `submit <activity_id> <file...>`

```bash
tronclass homework submit <activity_id> <file1> [file2 ...] [--draft]
tronclass hw s <activity_id> ./essay.pdf ./appendix.pdf
```

Uploads one or more files and submits them for the specified homework activity.

A confirmation prompt is shown before submitting, displaying the homework title and the file(s) to be submitted.

| Option | Description |
|---|---|
| `--draft` | Save as draft instead of final submission. Inspect with `homework view`. |

### Notes

- Multiple files can be submitted in one command.
- Folders are not supported — only individual files.
- Supported file types: any (MIME type detected automatically).
- The activity ID is the `id` from `homework list`.

### Example

```bash
# Find the homework ID
tronclass homework list <course_id>

# Read the prompt
tronclass homework view 2901222

# Submit a single file
tronclass homework submit 2901222 ./report.pdf

# Submit multiple files
tronclass homework submit 2901222 ./report.pdf ./data.xlsx

# Save as draft, then verify
tronclass homework submit 2901222 ./draft_report.pdf --draft
tronclass homework view 2901222
```


path: references/courses.md
content: # Courses Command Reference

```bash
tronclass courses list [--all] [--raw] [--fields f1,f2,...]
tronclass c list ...
```

## Options

| Option | Description |
|---|---|
| *(none)* | Show only **ongoing** courses (default) |
| `--all` | Show all courses including past and future |
| `--raw` | Print raw JSON response — useful for inspecting all available fields |
| `--fields f1,f2,...` | Customize displayed columns |

## Default Fields

`id, name, instructors.name`

The `id` column is the **course ID** needed for `activities list` and `homework list`.

## Available Fields (common)

| Field | Description |
|---|---|
| `id` | Course ID |
| `name` | Course name |
| `course_code` | Course code |
| `department` | Department |
| `semester` | Semester label |
| `instructors.name` | Instructor name (nested field) |
| `start_date` / `end_date` | Course date range |

Use `--raw` to see the full JSON and discover additional fields.

## Examples

```bash
# List ongoing courses (default)
tronclass courses list

# All courses including old ones
tronclass courses list --all

# Raw JSON for full field inspection
tronclass courses list --raw

# Custom columns
tronclass courses list --fields id,name,semester
```


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)