studip-router — Stud.IP files, sorted into your folders

Terms · Quick start · Usage · Configuration · Commands · FAQ · Troubleshooting

Course files in, your folder structure out. Most Stud.IP downloaders mirror the course's folder tree. studip-router files every document into the folders you already use — whatever you call them (Exercises, Übungen, Hausaufgaben, Slides, Skript, Exams/Past papers, …) — with per-course rules, because every lecturer organises their course differently:

studip

Press s, confirm the one-line summary, done. A second run downloads nothing unless something changed on Stud.IP.

_{The home screen: status cards on top, every common action on one key. All course names in the screenshots are made up.}

Contents

1. Terms in one sentence
2. Features
3. Quick start · Defaults
4. Requirements · Installation
5. Usage
6. Where files go · Configuration
7. Command reference
8. How it stays safe
9. Tricky files
10. FAQ
11. Troubleshooting
12. Development · Use of AI · Credits · License

Terms in one sentence

Features

Quick start

uv tool install studip-router

studip

The first start opens a setup in three steps. Every field is prefilled with a good guess, so usually you only press Enter:

Missing folders are created after one confirmation, each course folder with the same subfolders. Because their names say what they hold, files land in the right one from the first sync on — no rules needed.

Then: p shows where every file would go, s syncs. studip init is the same setup in the terminal.

_{One block, one command: the copy icon takes exactly one call.}

Requirements

• Python 3.11+, macOS or Linux. Windows is not supported (not tested; background sync and notifications do not exist there).
• An OS keychain: macOS Keychain, or a Secret Service keyring on Linux (GNOME Keyring, KWallet). On servers, WSL or containers without one, set STUDIP_ROUTER_PASSWORD instead (see Headless use); the password is never stored in a file.
• A Stud.IP instance with the JSON:API enabled and username/password login (local or LDAP accounts). Check: https://<your-studip>/jsonapi.php/v1/discovery must open in a browser.
• SSO-only accounts (Shibboleth/OIDC without a Stud.IP password) and two-factor authentication are not supported yet — contributions welcome, see docs/DESIGN.md.

Installation

Releases come from PyPI, built and uploaded by this repository's GitHub Actions (changes). A specific version: uv tool install studip-router==0.2.1. No uv yet? See its installation (one command; it brings its own Python). The unreleased state of main: uv tool install git+https://github.com/nbomers/studip-router.

cp shell/fish/completions/studip.fish ~/.config/fish/completions/

Usage

The terminal UI

j/k and arrow keys move, Enter opens, Esc goes back.

_{Left the preview — every file, its target and the rule that placed it. Right the settings — saved immediately, comments in the config file are kept.}

The command line

Everything works without the UI:

studip init

studip rules suggest --write

studip sync --dry-run

studip sync

Setup, add the suggested rules, see exactly what would happen, do it.

Defaults and how to change them

In the settings screen h/l switches options and Enter edits a text value; every change is saved at once. The config file (e in the settings, studip config edit) has the same keys, with comments kept.

Where files go

~/Uni/Semester 5/                  sync.root — you pick it in the setup
├── Quantum Cooking/               one folder per course (its target)
│   ├── Exercises/                 by a rule, or automatically from a Stud.IP
│   ├── Slides/                    folder name like "Übungen" or "Folien"
│   └── Sonstiges/                 everything else (sync.default_target)
└── Underwater Basket Weaving/

Courses you never set up are not synced, unless you set sync.only_configured_courses = false: then each gets a folder named like the course, created automatically.

Config, state and log stay outside your course folders (also on macOS): ~/.config/studip-router/config.toml and ~/.local/state/studip-router/.

Configuration

The config lives at ~/.config/studip-router/config.toml (studip config path). Most options are in the settings screen; rules are written in the file. The fully commented reference is config.example.toml.

[server]
base_url = "https://studip.example.edu"
username = "jdoe"                         # password: OS keychain only

[sync]
root = "~/Uni/Semester 5"
default_target = "Misc"                   # where files go that no rule matches

[courses.0123456789abcdef0123456789abcdef]   # Stud.IP course ID (`studip courses`)
name = "Quantum Cooking"
target = "Quantum Cooking"

[[courses.0123456789abcdef0123456789abcdef.rules]]
id = "sheets"
match = { folder = "Übungsblätter*", name_regex = '(?:blatt|sheet)[ _]?(\d+)' }
target = "Exercises"
rename = "Exercise_{1:02}{ext}"

Test a rule without downloading anything (also in the UI under r):

studip rules test quantum "Blatt 7.pdf" --folder "Übungsblätter"

Rule sheets
  → ~/Uni/Semester 5/Quantum Cooking/Exercises/Exercise_07.pdf

Command reference

Global options: --profile NAME (separate config + state, e.g. a second university), --json (machine-readable output for scripts, Raycast, Alfred, …).

How it stays safe

Found a security problem? See SECURITY.md.

Tricky files

FAQ

studip pdf-password set "Quantum Cooking"

Troubleshooting

Exit codes and JSON

For scripts: 0 success, 1 some files or courses failed, 2 invalid config or arguments, 3 login or keychain problem, 4 damaged state database, 75 another run is in progress, 130 interrupted. With --json, errors are printed as {"error": "..."}; the other fields of --json output may still grow, but existing ones are kept.

Uninstall

studip schedule uninstall          # background job (per profile: --profile NAME)
studip auth logout                 # Stud.IP password from the keychain
studip pdf-password list           # then `studip pdf-password remove COURSE` for each
uv tool uninstall studip-router    # or: pipx uninstall studip-router
rm -r ~/.config/studip-router ~/.local/state/studip-router

Your course folders and downloaded files are never touched.

Terms of use

The tool logs in with your own account and only reads what you can see in the browser. Check whether your university's terms of use allow automated access; keep the background interval reasonable (at least 15 minutes is enforced, 2 hours is the default). Licensed course material stays licensed after it is downloaded or unlocked.

Development

uv sync

uv run pytest

uv run ruff check . && uv run ruff format --check .

Ground rules, layout and conventions: CONTRIBUTING.md. Invariants, architecture and the Stud.IP API calls: docs/DESIGN.md. Changes: CHANGELOG.md.

Use of AI

The code was written with Claude (Anthropic) via Claude Code; the commits say so in their Co-Authored-By lines. What for:

• Writing code — modules, the terminal UI and the tests; run and checked with pytest and ruff before being adopted.
• Review and debugging — e.g. file names with decomposed umlauts (NFD) on Linux.
• Documentation — this README, the design notes and the changelog.

Tests run against a fake Stud.IP (tests/fake_studip.py); no real course data, IDs or accounts are in the repository.

Credits

License

The code is under the MIT license.

Not affiliated with the Stud.IP e.V. or any university.