### Install kulms CLI using uv

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Installs the kulms CLI tool using the uv package manager. Ensure uv is installed and configured.

```powershell
uv tool install kulms
```

--------------------------------

### KULMS CLI Installation

Source: https://context7.com/youseiushida/kulms/llms.txt

Install the KULMS CLI using pip or uv. This command is the first step to using the command-line interface for KULMS.

```bash
# インストール
pip install kulms
# または
uv tool install kulms
```

--------------------------------

### Get All Announcements

Source: https://context7.com/youseiushida/kulms/llms.txt

Retrieves announcements from all courses. Prints the site title, announcement title, creator, and creation date.

```python
announcements = client.announcements.list()
for ann in announcements:
    print(f"[{ann.site_title}] {ann.title}")
    print(f"  作成者: {ann.created_by_display_name}")
    print(f"  作成日: {ann.created_on}")
```

--------------------------------

### Install kulms CLI using pipx

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Installs the kulms CLI tool as an isolated application using pipx.

```powershell
pipx install kulms
```

--------------------------------

### Get All Calendar Events

Source: https://context7.com/youseiushida/kulms/llms.txt

Retrieves all calendar events across all courses. Prints event title, course name, start time, and type.

```python
events = client.calendar.list()
for event in events:
    print(f"イベント: {event.title}")
    print(f"  コース: {event.site_name}")
    print(f"  開始: {event.first_time}")
    print(f"  種別: {event.type}")
```

--------------------------------

### Install kulms in editable mode for development

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Installs the kulms package in editable mode from the current directory, suitable for development.

```powershell
uv tool install --editable .
```

--------------------------------

### Install kulms using pip

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Installs the kulms Python package using pip. This command is for using kulms as a library.

```powershell
python -m pip install kulms
```

--------------------------------

### Get Course Tabs

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Fetches the pages, tabs, and tools for a specific course.

```python
tabs = client.courses.tabs("COURSE_ID")
```

--------------------------------

### Get All Assignments

Source: https://context7.com/youseiushida/kulms/llms.txt

Retrieves all assignments across all courses. Prints assignment title, course context, due date, and status.

```python
all_assignments = client.assignments.list()
for assignment in all_assignments:
    print(f"課題: {assignment.title}")
    print(f"  コース: {assignment.context}")
    print(f"  締切: {assignment.due_time_string}")
    print(f"  ステータス: {assignment.status}")
```

--------------------------------

### Making Direct API Requests

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Use `client.direct.get_json` for GET requests returning JSON, `client.direct.post_json` for POST requests returning JSON, and `client.direct.request` for general HTTP requests, including file downloads.

```python
raw_sites = client.direct.get_json("site")
assignment_doc = client.direct.get_json("/direct/assignment/my")
response = client.direct.request("GET", "/access/content/group/example/file.pdf")
```

--------------------------------

### Get Course Details and Tabs

Source: https://context7.com/youseiushida/kulms/llms.txt

Fetch specific course details with `client.courses.get()` and inspect its tab structure using `tabs()`.

```python
from kulms import KULMSClient

client = KULMSClient.from_credentials(
    username="your-ecs-id",
    password="your-password",
    totp_secret="ABCDEFGHIJKLMNOP",
)

# Get course details
course = client.courses.get("2025-course-id-12345")
print(f"Course Name: {course.title}")
print(f"Description: {course.description}")
print(f"Entity URL: {course.entity_url}")

# Get course tab list
tabs = client.courses.tabs("2025-course-id-12345")
for tab in tabs:
    print(f"Tab: {tab.title}")
    for tool in tab.tools:
        print(f"  - {tool.title} (tool_id: {tool.tool_id})")
# Example output:
# Tab: Overview
#   - Overview (tool_id: sakai.iframe.site)
# Tab: Course Materials
#   - Resources (tool_id: sakai.resources)
# Tab: Assignments
#   - Assignments (tool_id: sakai.assignment.grades)
```

--------------------------------

### Update shell for uv tools

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Updates the shell environment to recognize commands installed by uv tool. Run this after installing or updating tools.

```powershell
uv tool update-shell
```

--------------------------------

### Get courses in JSON format

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Retrieves the list of courses from KULMS and outputs the data in JSON format.

```powershell
kulms courses --json
```

--------------------------------

### Get Calendar Events within a Date Range

Source: https://context7.com/youseiushida/kulms/llms.txt

Retrieves calendar events that fall within a specified start and end date.

```python
april_events = client.calendar.list(
    first_date="2025-04-01",
    last_date="2025-04-30",
)
for event in april_events:
    print(f"{event.title} - {event.first_time}")
```

--------------------------------

### Get List of Courses

Source: https://context7.com/youseiushida/kulms/llms.txt

Retrieve a list of enrolled courses using `client.courses.list()`. Supports pagination and iteration for all courses.

```python
from kulms import KULMSClient

client = KULMSClient.from_credentials(
    username="your-ecs-id",
    password="your-password",
    totp_secret="ABCDEFGHIJKLMNOP",
)

# Get course list (default: max 100 items)
courses = client.courses.list(limit=50, offset=0)
for course in courses:
    print(f"ID: {course.id}")
    print(f"Title: {course.title}")
    print(f"Type: {course.type}")
    print("---")

# Get all courses using an iterator
for course in client.courses.iter(page_size=100):
    print(f"{course.id}: {course.title}")

# Check if a course exists
if client.courses.exists("2025-course-id-12345"):
    print("Course exists")
```

--------------------------------

### Get Announcements for a Specific Course

Source: https://context7.com/youseiushida/kulms/llms.txt

Retrieves announcements only for a specified course.

```python
course_news = client.announcements.list("2025-course-id-12345")
```

--------------------------------

### Get Current User Information

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Fetches the current user's information from the /direct/user/current endpoint.

```python
user = client.users.current()
print(user.eid, user.display_name)
```

--------------------------------

### Uninstall kulms CLI using uv

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Uninstalls the kulms CLI tool that was installed using uv.

```powershell
uv tool uninstall kulms
```

--------------------------------

### Get a Specific Assignment by ID

Source: https://context7.com/youseiushida/kulms/llms.txt

Retrieves a single assignment using its unique identifier. Prints the assignment's title and instructions.

```python
assignment = client.assignments.get("assignment-id-12345")
print(f"課題名: {assignment.title}")
print(f"説明: {assignment.instructions}")
```

--------------------------------

### Get Assignments for a Specific Course

Source: https://context7.com/youseiushida/kulms/llms.txt

Retrieves assignments for a single, specified course.

```python
course_assignments = client.assignments.list("2025-course-id-12345")
```

--------------------------------

### Get Calendar Events for a Specific Course

Source: https://context7.com/youseiushida/kulms/llms.txt

Retrieves calendar events only for a specified course.

```python
course_events = client.calendar.list("2025-course-id-12345")
```

--------------------------------

### KULMS CLI Direct API Calls

Source: https://context7.com/youseiushida/kulms/llms.txt

Make direct API calls using the 'kulms direct' command. Supports GET requests with optional raw output and describe endpoints.

```bash
# Direct API を直接呼び出す
kulms direct get site
kulms direct get /direct/user/current.json
kulms direct get /direct/site.json --raw
kulms direct describe
kulms direct describe assignment
```

--------------------------------

### Get Today's Announcements (MOTD)

Source: https://context7.com/youseiushida/kulms/llms.txt

Retrieves announcements for the current day, often referred to as Message of the Day (MOTD). Prints title and a truncated body.

```python
motd = client.announcements.motd(days=1)
for ann in motd:
    print(f"{ann.title}: {ann.body[:100]}...")
```

--------------------------------

### Get Current User Information

Source: https://context7.com/youseiushida/kulms/llms.txt

Retrieves information about the currently logged-in user. Includes EID, display name, email, and name components.

```python
user = client.users.current()
print(f"ECS-ID: {user.eid}")
print(f"表示名: {user.display_name}")
print(f"メール: {user.email}")
print(f"姓: {user.last_name}")
print(f"名: {user.first_name}")
print(f"タイプ: {user.type}")
```

--------------------------------

### Get Current Session Information

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Retrieves the current Sakai session information from the /direct/session/current endpoint.

```python
session = client.sessions.current()
print(session.user_eid, session.active)
```

--------------------------------

### Direct API Calls

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Makes direct calls to KULMS API endpoints not covered by high-level commands. Use --raw to view the raw response. Use 'describe' to get API endpoint information.

```powershell
kulms direct get site
```

```powershell
kulms direct get /direct/site.json
```

```powershell
kulms direct get /direct/user/current.json
```

```powershell
kulms direct get /direct/site.json --raw
```

```powershell
kulms direct describe
```

```powershell
kulms direct describe assignment
```

```powershell
kulms direct describe content
```

--------------------------------

### Get Current Session Information

Source: https://context7.com/youseiushida/kulms/llms.txt

Retrieves information about the current Sakai session. Useful for session validation, showing ID, user EID, activity status, and timings.

```python
session = client.sessions.current()
print(f"セッション ID: {session.id}")
print(f"ユーザー EID: {session.user_eid}")
print(f"アクティブ: {session.active}")
print(f"作成日時: {session.creation_time}")
print(f"最終アクセス: {session.last_accessed_time}")
print(f"最大非アクティブ時間: {session.max_inactive_interval} 秒")
```

--------------------------------

### Direct API Calls with KULMSClient

Source: https://context7.com/youseiushida/kulms/llms.txt

Access KULMS endpoints directly using client.direct. Supports GET, POST, and streaming requests. Paths are automatically normalized. Use ensure_json_suffix=False for endpoints not ending in .json.

```python
from kulms import KULMSClient

client = KULMSClient.from_credentials(
    username="your-ecs-id",
    password="your-password",
    totp_secret="ABCDEFGHIJKLMNOP",
)

# GET リクエスト（パスは自動で /direct/site.json に正規化）
sites = client.direct.get_json("site")
print(f"サイト数: {len(sites.get('site_collection', []))}")

# 各種パス形式に対応
user = client.direct.get_json("/direct/user/current.json")
assignment = client.direct.get_json("/direct/assignment/my")

# POST リクエスト
result = client.direct.post_json(
    "/direct/some-endpoint",
    data={"key": "value"},
)

# JSON 形式を強制しない場合
result = client.direct.get_json(
    "/direct/describe",
    ensure_json_suffix=False,
)

# 生の HTTP レスポンスを取得
response = client.direct.request("GET", "/access/content/group/example/file.pdf")
with open("file.pdf", "wb") as f:
    f.write(response.content)

# ストリーミングダウンロード
with client.direct.stream("GET", "/access/content/group/example/large-file.zip") as response:
    with open("large-file.zip", "wb") as f:
        for chunk in response.iter_bytes():
            f.write(chunk)
```

--------------------------------

### KULMS CLI Resources Listing

Source: https://context7.com/youseiushida/kulms/llms.txt

List all learning resources for a given course.

```bash
# 授業資料の一覧
kulms resources COURSE_ID
```

--------------------------------

### KULMS CLI Course Listing

Source: https://context7.com/youseiushida/kulms/llms.txt

List all available courses. Use --json flag for JSON output.

```bash
# コース一覧
kulms courses
kulms courses --json  # JSON 出力
```

--------------------------------

### KULMS CLI Resources Download

Source: https://context7.com/youseiushida/kulms/llms.txt

Download learning resources for a course. Options include specifying destination, dry run, and overwriting existing files.

```bash
# 授業資料のダウンロード
kulms resources COURSE_ID --download
kulms resources COURSE_ID --download --dest ./downloads
kulms resources COURSE_ID --download --dry-run  # 保存せず確認のみ
kulms resources COURSE_ID --download --overwrite
```

--------------------------------

### Initialize KULMSClient with Credentials

Source: https://context7.com/youseiushida/kulms/llms.txt

Initialize the KULMSClient using username, password, and TOTP secret. The client manages all KULMS access.

```python
from kulms import KULMSClient

# Initialize directly from credentials
client = KULMSClient.from_credentials(
    username="your-ecs-id",
    password="your-password",
    totp_secret="ABCDEFGHIJKLMNOP",  # TOTP secret
)
```

```python
# Use as a context manager
with KULMSClient.from_credentials(
    username="your-ecs-id",
    password="your-password",
    totp_secret="ABCDEFGHIJKLMNOP",
) as client:
    session = client.sessions.current()
    print(f"Logging in: {session.user_eid}")
    # Session is automatically closed
```

```python
# When passing a one-time password directly
client = KULMSClient.from_credentials(
    username="your-ecs-id",
    password="your-password",
    onetime_password="123456",  # 6-digit one-time password
)
```

```python
# Using an OTP callback
client = KULMSClient.from_credentials(
    username="your-ecs-id",
    password="your-password",
    otp_callback=lambda: input("One-time password: "),
)
```

--------------------------------

### Download Course Resources

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Downloads resources for a specific course. Use --dest to specify a download directory, --dry-run to preview, --overwrite to replace existing files, --allow-external to include external links, and --max-bytes to set a file size limit.

```powershell
kulms resources COURSE_ID --download
```

```powershell
kulms resources COURSE_ID --download --dest .\downloads
```

```powershell
kulms resources COURSE_ID --download --dry-run
```

```powershell
kulms resources COURSE_ID --download --overwrite
```

```powershell
kulms resources COURSE_ID --download --allow-external
```

```powershell
kulms resources COURSE_ID --download --max-bytes 104857600
```

--------------------------------

### Download Course Resources

Source: https://context7.com/youseiushida/kulms/llms.txt

Download course materials in bulk using `client.resources.download()`. Supports dry runs, overwriting, and external URL options.

```python
from kulms import KULMSClient

client = KULMSClient.from_credentials(
    username="your-ecs-id",
    password="your-password",
    totp_secret="ABCDEFGHIJKLMNOP",
)
```

--------------------------------

### Download Resources (Actual Download)

Source: https://context7.com/youseiushida/kulms/llms.txt

Performs actual resource download to a specified directory. Includes options for overwriting, external links, and file size limits.

```python
results = client.resources.download(
    "2025-course-id-12345",
    dest="./KULMS",           # 保存先ディレクトリ
    overwrite=False,          # 既存ファイルはスキップ
    allow_external=False,     # 外部 URL はスキップ
    max_file_size=512*1024*1024,  # 最大512MiB
)
for result in results:
    if result.status == "downloaded":
        print(f"ダウンロード完了: {result.path} ({result.bytes} bytes)")
    elif result.status == "skipped":
        print(f"スキップ: {result.source_url} - {result.message}")
    elif result.status == "failed":
        print(f"失敗: {result.source_url} - {result.message}")
```

--------------------------------

### List Course Resources

Source: https://context7.com/youseiushida/kulms/llms.txt

Retrieve course materials (files and folders) using `client.resources.list()`. Provides download URLs and distinguishes between files and collections.

```python
from kulms import KULMSClient

client = KULMSClient.from_credentials(
    username="your-ecs-id",
    password="your-password",
    totp_secret="ABCDEFGHIJKLMNOP",
)

# Get course resource list
resources = client.resources.list("2025-course-id-12345")
for item in resources:
    kind = "Folder" if item.is_collection else "File"
    print(f"[{kind}] {item.display_name}")
    print(f"  Size: {item.size or '---'} bytes")
    print(f"  URL: {item.download_url}")

# Get resources related to the current user
my_resources = client.resources.list_my()
for item in my_resources:
    print(f"{item.display_name}: {item.download_url}")
```

--------------------------------

### Download Resources (Dry Run)

Source: https://context7.com/youseiushida/kulms/llms.txt

Simulates resource download without saving files. Useful for checking paths and statuses before actual download.

```python
results = client.resources.download(
    "2025-course-id-12345",
    dest="./downloads",
    dry_run=True,  # 実際には保存しない
)
for result in results:
    print(f"[{result.status}] {result.path}")
```

--------------------------------

### Download course resources using kulms CLI

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Downloads all resources for a specific course to the local directory. Replace COURSE_ID with the actual course identifier.

```powershell
kulms resources COURSE_ID --download
```

--------------------------------

### List course resources using kulms CLI

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Lists the resources (course materials) for a specific course. Replace COURSE_ID with the actual course identifier.

```powershell
kulms resources COURSE_ID
```

--------------------------------

### List Resources in a Course

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Retrieves a list of resources within a specified course. Corresponds to Sakai Direct API's 'content'.

```python
items = client.resources.list("COURSE_ID")
```

--------------------------------

### Download Course Resources

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Downloads files from a specified course. Folders are excluded, and only files are saved. By default, it only fetches from KULMS's /access/content/ and skips external URLs. dry_run=True simulates the download without saving files.

```python
results = client.resources.download(
    "COURSE_ID",
    dest="KULMS",
    dry_run=True,
)
```

--------------------------------

### Show kulms CLI help

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Displays the help message for the kulms CLI, showing available commands and options.

```powershell
kulms --help
```

--------------------------------

### List Courses

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Retrieves a list of courses. Corresponds to Sakai's _limit and _start parameters.

```python
courses = client.courses.list(limit=50)
```

--------------------------------

### Show course details

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Displays detailed information about a specific course, including its ID, name, and description.

```powershell
kulms course show COURSE_ID
```

--------------------------------

### List courses using kulms CLI

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Fetches and displays a list of available courses from KULMS. The output includes course IDs which are used in subsequent commands.

```powershell
kulms courses
```

--------------------------------

### KULMS CLI Course Details

Source: https://context7.com/youseiushida/kulms/llms.txt

Show detailed information for a specific course using its ID. Also lists available tabs for the course.

```bash
# コース詳細
kulms course show COURSE_ID
kulms course tabs COURSE_ID
```

--------------------------------

### List courses using a specific profile

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Fetches and displays course lists for a specified profile. Ensures commands operate within the context of the chosen profile.

```powershell
kulms --profile main courses
```

--------------------------------

### List course tabs

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Retrieves and displays the available tabs (sections) for a given course, along with their corresponding Sakai tool IDs.

```powershell
kulms course tabs COURSE_ID
```

--------------------------------

### client.direct - Low-level Sakai Direct API Client

Source: https://github.com/youseiushida/kulms/blob/main/README.md

The `client.direct` module provides a low-level client for calling the unwrapped Sakai Direct API. It handles HTTP requests through KULMS services and offers methods for JSON retrieval and posting.

```APIDOC
## `client.direct`

### Description

A low-level client for calling the unwrapped Sakai Direct API via KULMS services.

### Methods

- **`request(method, path_or_url, **kwargs)`**: Sends an HTTP request through the KULMS service using kuauth. Accepts additional keyword arguments.
- **`get_json(path_or_url, params=None, ensure_json_suffix=True)`**: Performs a GET request and returns the response as JSON.
- **`post_json(path_or_url, data=None, json_data=None, params=None, ensure_json_suffix=True)`**: Performs a POST request and returns the response as JSON. Accepts both `data` and `json_data` for the request body.

### Path Normalization

The client normalizes input paths to the `/direct/` endpoint with a `.json` suffix, except for paths starting with `/access/` or absolute URLs.

| Input Example     | Actual Handling     |
|-------------------|---------------------|
| `site`            | `/direct/site.json` |
| `/site`           | `/direct/site.json` |
| `/direct/site`    | `/direct/site.json` |
| `/direct/site.json`| `/direct/site.json` |
| `/access/content/...`| `/access/content/...` |
| `https://...`     | Absolute URL        |

### Usage Examples

```python
raw_sites = client.direct.get_json("site")
assignment_doc = client.direct.get_json("/direct/assignment/my")
response = client.direct.request("GET", "/access/content/group/example/file.pdf")
```

### Library Models

Models inherit from Pydantic v2's `BaseModel` with `extra="allow"`, preserving extra fields from Sakai. `populate_by_name=True` allows using both Python's snake_case and Sakai's alias names.

| Model           | Key Fields                                                                 |
|-----------------|----------------------------------------------------------------------------|
| `Course`        | `id`, `title`, `type`, `description`, `entity_id`, `entity_title`, `entity_url` |
| `CourseTab`     | `id`, `title`, `site_id`, `url`, `tools`                                     |
| `CourseTool`    | `id`, `title`, `tool_id`, `placement_id`, `site_id`, `page_id`, `url`       |
| `ResourceItem`  | `id`, `title`, `name`, `type`, `url`, `path`, `container`, `size`, `children` |
| `DownloadResult`| `source_url`, `path`, `status`, `bytes`, `message`                         |
| `Assignment`    | `id`, `title`, `context`, `status`, `instructions`, `due_time`, `due_time_string`, `open_time`, `close_time` |
| `Announcement`  | `id`, `announcement_id`, `title`, `body`, `site_id`, `site_title`, `created_on`, `created_by_display_name` |
| `CalendarEvent` | `event_id`, `title`, `description`, `site_id`, `site_name`, `first_time`, `duration`, `type` |
| `SessionInfo`   | `id`, `active`, `user_id`, `user_eid`, `creation_time`, `current_time`, `last_accessed_time`, `max_inactive_interval` |
| `User`          | `id`, `eid`, `display_id`, `display_name`, `email`, `first_name`, `last_name`, `type` |

#### `ResourceItem` Properties

- **`display_name`**: Returns display name prioritizing `title`, `name`, then `id`.
- **`download_url`**: Infers download URL from fields like `webLinkUrl`, `downloadUrl`, `contentUrl`, `url`, `entityURL`.
- **`is_collection`**: Returns `True` if the item is a folder (collection).

### Library Exceptions

| Exception       | Meaning                                                                    |
|-----------------|----------------------------------------------------------------------------|
| `KULMSError`    | Base exception for this package.                                           |
| `AuthExpiredError`| Raised on session expiration, unauthorized access, or redirection to login page. |
| `APIError`      | Raised for non-JSON responses, HTTP errors, or invalid JSON.               |
| `NotFoundError` | Raised for HTTP 404 errors. Subclass of `APIError`.                        |

CLI exit codes: 2 for `AuthExpiredError` (prompts `kulms auth login`), 1 for other `KULMSError` exceptions.
```

--------------------------------

### Iterate Through Courses

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Yields courses sequentially while handling pagination.

```python
for course in client.courses.iter(page_size=100):
    print(course.id, course.title)
```

--------------------------------

### Session Management with JsonFileSessionStore

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Demonstrates how to save and load session cookies using JsonFileSessionStore for persistent authentication.

```APIDOC
## Session Management with JsonFileSessionStore

### Description
This section shows how to use `JsonFileSessionStore` to persist session cookies, allowing for session loading and avoiding repeated authentication flows. It also covers handling `AuthExpiredError` and re-authenticating if the loaded session is invalid.

### Method
N/A (Code Example)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
from pathlib import Path

from kulms import AuthExpiredError, KULMSClient
from kulms.session import JsonFileSessionStore

store = JsonFileSessionStore(Path("kulms.cookies.json"))

client = KULMSClient.from_credentials(
    username,
    password,
    totp_secret=totp_secret,
    session_store=store,
    load_session=True,
    trust_loaded_session=True,
)

try:
    client.sessions.current()
except AuthExpiredError:
    client = KULMSClient.from_credentials(
        username,
        password,
        totp_secret=totp_secret,
        session_store=store,
        load_session=False,
    )
    client.sessions.current()
    client.save_session()
```

### Response
N/A

### Notes
- `load_session=True` attempts to load saved cookies.
- `trust_loaded_session=True` bypasses SSO flow if valid cookies are loaded.
- Expired cookies are skipped. `AuthExpiredError` is raised if the session becomes invalid server-side.
```

--------------------------------

### Login to KULMS CLI

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Initiates the login process for the kulms CLI. This command will prompt for credentials and potentially TOTP secrets.

```powershell
kulms auth login
```

--------------------------------

### Initialize KULMSClient with One-Time Password

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Initializes the KULMS client with a one-time password directly or via a callback function for dynamic OTP generation.

```python
client = KULMSClient.from_credentials(
    username,
    password,
    onetime_password="123456",
)
```

```python
client = KULMSClient.from_credentials(
    username,
    password,
    otp_callback=lambda: input("OTP: "),
)
```

--------------------------------

### Resource Download API

Source: https://context7.com/youseiushida/kulms/llms.txt

API for downloading course resources. Supports dry runs to preview downloads and actual downloads with options for destination, overwriting, external links, and file size limits.

```APIDOC
## POST /api/resources/download

### Description
Downloads course resources. Can be used in a dry run mode to preview files without downloading.

### Method
POST

### Endpoint
/api/resources/download

### Parameters
#### Request Body
- **course_id** (string) - Required - The ID of the course from which to download resources.
- **dest** (string) - Required - The destination directory for downloads.
- **dry_run** (boolean) - Optional - If true, simulates the download process without saving files.
- **overwrite** (boolean) - Optional - If true, overwrites existing files. Defaults to false.
- **allow_external** (boolean) - Optional - If true, allows downloading from external URLs. Defaults to false.
- **max_file_size** (integer) - Optional - The maximum file size in bytes to download.

### Request Example
```json
{
  "course_id": "2025-course-id-12345",
  "dest": "./downloads",
  "dry_run": true
}
```

### Response
#### Success Response (200)
- **results** (array) - A list of download results, each containing status and path.
  - **status** (string) - The status of the download operation (e.g., 'planned', 'downloaded', 'skipped', 'failed').
  - **path** (string) - The local path of the file.
  - **source_url** (string) - The URL of the source file.
  - **message** (string) - A message providing details about the status.
  - **bytes** (integer) - The size of the downloaded file in bytes.

#### Response Example
```json
[
  {
    "status": "planned",
    "path": "./downloads/情報学概論/第1回/lecture01.pdf"
  },
  {
    "status": "planned",
    "path": "./downloads/情報学概論/第2回/lecture02.pdf"
  }
]
```
```

--------------------------------

### List Announcements

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Retrieves a list of announcements, optionally filtered by course ID and date range. If site_id is None, it fetches announcements across all courses.

```python
announcements = client.announcements.list(limit=20)
```

--------------------------------

### List Calendar Events by Date Range

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Retrieves calendar events within a specified date range. If site_id is None, it fetches events across all courses.

```python
events = client.calendar.list(first_date="2026-04-01", last_date="2026-04-30")
```

--------------------------------

### List Announcements

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Lists announcements across all courses or for a specific course. Filter by number of days using --days, by limit using --limit, or by date range using --from and --to.

```powershell
kulms announcements
```

```powershell
kulms announcements COURSE_ID
```

```powershell
kulms announcements --days 7
```

```powershell
kulms announcements --limit 20
```

```powershell
kulms announcements --from 2026-04-01 --to 2026-04-30
```

--------------------------------

### Resources API

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Enables management and download of course resources (files and collections) within KULMS.

```APIDOC
## Resources API

### Description
The `client.resources` object handles course materials, referred to as 'Resources' in KULMS and 'content' in Sakai Direct API. It allows listing resources within a course, listing resources associated with the current user, and downloading files.

### Method
N/A (High-level API methods)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
# List resources for a specific course
items = client.resources.list("COURSE_ID")

# Download resources for a course (dry run)
results = client.resources.download(
    "COURSE_ID",
    dest="KULMS",
    dry_run=True,
)
```

### Response
N/A (Specific response structures depend on the method called)

### Notes
- `list(site_id)`: Gets a list of resources for a given course.
- `list_my()`: Gets a list of resources associated with the current user.
- `download(...)`: Downloads files from a course. It excludes folders, saves files to `dest / course title / resource path`, and by default only fetches from KULMS `/access/content/` excluding external URLs. Parameters include `dest`, `overwrite`, `dry_run`, `allow_external`, and `max_file_size`.
```

--------------------------------

### KULMS CLI Profile Management

Source: https://context7.com/youseiushida/kulms/llms.txt

Use different KULMS profiles for authentication and configuration. Allows managing multiple sets of credentials or settings.

```bash
# プロファイルを使い分ける
kulms --profile main auth login
kulms --profile main courses
```

--------------------------------

### List Course Announcements

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Retrieves announcements for a specific course using its site ID.

```python
course_news = client.announcements.list("COURSE_ID")
```

--------------------------------

### List Assignments for a Specific Course

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Retrieves assignments for a particular course using its site ID.

```python
course_assignments = client.assignments.list("COURSE_ID")
```

--------------------------------

### KULMS CLI Announcements Listing

Source: https://context7.com/youseiushida/kulms/llms.txt

List announcements, with options to filter by days, limit the number of results, or specify a course.

```bash
# お知らせ一覧
kulms announcements
kulms announcements --days 7
kulms announcements --limit 20
kulms announcements COURSE_ID
```

--------------------------------

### List Calendar Events for a Specific Course

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Retrieves calendar events for a particular course using its site ID.

```python
course_events = client.calendar.list("COURSE_ID")
```

--------------------------------

### Save Session with JsonFileSessionStore

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Saves cookies using JsonFileSessionStore in the library. load_session=True loads saved cookies, and trust_loaded_session=True treats loaded cookies as ready for use, skipping unnecessary SSO flows. Expired cookies are skipped, and AuthExpiredError is raised if the session is invalidated server-side.

```python
from pathlib import Path

from kulms import AuthExpiredError, KULMSClient
from kulms.session import JsonFileSessionStore

store = JsonFileSessionStore(Path("kulms.cookies.json"))

client = KULMSClient.from_credentials(
    username,
    password,
    totp_secret=totp_secret,
    session_store=store,
    load_session=True,
    trust_loaded_session=True,
)

try:
    client.sessions.current()
except AuthExpiredError:
    client = KULMSClient.from_credentials(
        username,
        password,
        totp_secret=totp_secret,
        session_store=store,
        load_session=False,
    )
    client.sessions.current()
    client.save_session()
```

--------------------------------

### Filter Announcements by Creation Date

Source: https://context7.com/youseiushida/kulms/llms.txt

Retrieves announcements within a specific date range.

```python
filtered = client.announcements.list(
    from_date="2025-04-01",
    to_date="2025-04-30",
)
```

--------------------------------

### List Calendar Events

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Lists calendar events across all courses or for a specific course. Filter by date range using --from and --to, or --first-date and --last-date.

```powershell
kulms calendar
```

```powershell
kulms calendar COURSE_ID
```

```powershell
kulms calendar --from 2026-04-01 --to 2026-04-30
```

```powershell
kulms calendar --first-date 2026-04-01 --last-date 2026-04-30
```

--------------------------------

### KULMS CLI Assignments Listing

Source: https://context7.com/youseiushida/kulms/llms.txt

List assignments, optionally filtered by course ID, status (OPEN, DUE), or date range.

```bash
# 課題一覧
kulms assignments
kulms assignments COURSE_ID
kulms assignments --status OPEN
kulms assignments --status OPEN --status DUE
kulms assignments --from 2025-04-20 --to 2025-05-10
```

--------------------------------

### Forget KULMS credentials and session

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Removes all stored credentials (username, password, TOTP secret) from keyring and logs out the CLI.

```powershell
kulms auth forget
```

--------------------------------

### KULMS CLI Calendar View

Source: https://context7.com/youseiushida/kulms/llms.txt

Display calendar events within a specified date range.

```bash
# カレンダー
kulms calendar
kulms calendar --from 2025-04-01 --to 2025-04-30
```

--------------------------------

### Calendar API

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Enables retrieval of calendar events, both for all courses and specific courses.

```APIDOC
## Calendar API

### Description
The `client.calendar` object allows you to retrieve calendar events. You can fetch events across all courses or for a specific course within a given date range.

### Method
N/A (High-level API methods)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
# List calendar events for April 2026
events = client.calendar.list(first_date="2026-04-01", last_date="2026-04-30")

# List calendar events for a specific course
course_events = client.calendar.list("COURSE_ID")
```

### Response
N/A (Specific response structures depend on the method called)

### Notes
- `list(site_id=None, first_date=None, last_date=None)`: Retrieves a list of calendar events. If `site_id` is `None`, it uses `/direct/calendar/my` for all courses; otherwise, it uses `/direct/calendar/site/{site_id}`.
- `first_date` and `last_date`: Define the date range for events.
```

--------------------------------

### Courses API

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Provides methods to interact with course information, including listing, retrieving details, and managing course tabs.

```APIDOC
## Courses API

### Description
The `client.courses` object allows you to manage and retrieve information about courses and Sakai sites. It supports listing courses, iterating through them with pagination, fetching detailed information, and accessing course tabs and tools.

### Method
N/A (High-level API methods)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
# Get a list of courses with a limit
courses = client.courses.list(limit=50)

# Iterate through courses with pagination
for course in client.courses.iter(page_size=100):
    print(course.id, course.title)

# Get tabs for a specific course
tabs = client.courses.tabs("COURSE_ID")
```

### Response
N/A (Specific response structures depend on the method called)

### Notes
- `list(limit=100, offset=0)`: Retrieves a list of courses, corresponding to Sakai's `_limit` and `_start` parameters.
- `iter(page_size=100)`: Yields courses iteratively, handling pagination.
- `get(site_id, include_groups=False)`: Fetches detailed information for a specific course.
- `tabs(site_id, props=False, config=False)`: Retrieves a list of pages, tabs, and tools within a course.
- `exists(site_id)`: Checks if a course exists.
```

--------------------------------

### Sessions API

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Provides access to current Sakai session information.

```APIDOC
## Sessions API

### Description
The `client.sessions` object allows you to retrieve information about the current Sakai session.

### Method
N/A (High-level API methods)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
session = client.sessions.current()
print(session.user_eid, session.active)
```

### Response
N/A (Specific response structures depend on the method called)

### Notes
- `current()`: Fetches the current session details using the `/direct/session/current` endpoint.
```

--------------------------------

### Users API

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Provides access to current user information.

```APIDOC
## Users API

### Description
The `client.users` object allows you to retrieve information about the currently authenticated user.

### Method
N/A (High-level API methods)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
user = client.users.current()
print(user.eid, user.display_name)
```

### Response
N/A (Specific response structures depend on the method called)

### Notes
- `current()`: Fetches the current user's details using the `/direct/user/current` endpoint.
```

--------------------------------

### View Dashboard

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Displays a combined view of assignments, announcements, and calendar events. This provides a quick overview, but detailed filtering is better handled by individual commands.

```powershell
kulms dashboard
```

--------------------------------

### KULMS CLI Dashboard

Source: https://context7.com/youseiushida/kulms/llms.txt

Display a consolidated dashboard view including assignments, announcements, and calendar events.

```bash
# ダッシュボード（課題・お知らせ・カレンダーをまとめて表示）
kulms dashboard
```

--------------------------------

### List Assignments by Date Range

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Retrieves assignments within a specified date range based on their due dates. Supports string, date, datetime, epoch seconds, and epoch milliseconds for date inputs. The date range is inclusive.

```python
upcoming = client.assignments.list(
    status=["OPEN", "DUE"],
    from_date="2026-04-20",
    to_date="2026-05-10",
)
```

--------------------------------

### Manage Sessions with JsonFileSessionStore

Source: https://context7.com/youseiushida/kulms/llms.txt

Persist session cookies to a file for session reuse without re-login. Handles AuthExpiredError if the session expires.

```python
from pathlib import Path
from kulms import AuthExpiredError, KULMSClient
from kulms.session import JsonFileSessionStore

# Create a session store
store = JsonFileSessionStore(Path("kulms.cookies.json"))

# Initialize client by loading session
client = KULMSClient.from_credentials(
    username="your-ecs-id",
    password="your-password",
    totp_secret="ABCDEFGHIJKLMNOP",
    session_store=store,
    load_session=True,           # Load saved cookies
    trust_loaded_session=True,   # Trust loaded session
)

try:
    # Check session validity
    session = client.sessions.current()
    print(f"Session valid: {session.user_eid}, active={session.active}")
except AuthExpiredError:
    # Re-login if session expired
    client = KULMSClient.from_credentials(
        username="your-ecs-id",
        password="your-password",
        totp_secret="ABCDEFGHIJKLMNOP",
        session_store=store,
        load_session=False,  # New login
    )
    client.sessions.current()
    client.save_session()  # Save session
    print("Session updated")
```

--------------------------------

### Login to KULMS with a specific profile

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Logs in to KULMS using a named profile. This allows managing multiple accounts or environments separately.

```powershell
kulms --profile main auth login
```

--------------------------------

### JSON Output for CLI Commands

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Enables JSON output for many CLI commands, useful for programmatic processing. This output format aims to preserve Sakai's camelCase field names.

```powershell
kulms assignments --status OPEN --json
```

```powershell
kulms resources COURSE_ID --download --dry-run --json
```

--------------------------------

### List Assignments

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Lists assignments across all courses or for a specific course. Filter by status using --status (can be specified multiple times) and by date range using --from and --to.

```powershell
kulms assignments
```

```powershell
kulms assignments COURSE_ID
```

```powershell
kulms assignments --status OPEN
```

```powershell
kulms assignments --status OPEN --status DUE
```

```powershell
kulms assignments --from 2026-04-20 --to 2026-04-30
```

```powershell
kulms assignments --status OPEN --from 2026-04-20 --to 2026-05-10
```

--------------------------------

### Check kulms CLI authentication status

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Displays the current authentication status and session information for the kulms CLI.

```powershell
kulms auth status
```

--------------------------------

### KULMS CLI Authentication Login

Source: https://context7.com/youseiushida/kulms/llms.txt

Log in to KULMS via the CLI. Prompts for username, password, and TOTP secret. The TOTP secret can be saved in the keyring.

```bash
# ログイン
kulms auth login
# Username: your-ecs-id
# Password: (非表示入力)
# Save TOTP secret in keyring? [y/N]: y
# TOTP secret: (TOTP シークレット)
```

--------------------------------

### User Information API

Source: https://context7.com/youseiushida/kulms/llms.txt

API for retrieving information about the currently logged-in user.

```APIDOC
## GET /api/users/current

### Description
Retrieves the profile information of the currently authenticated user.

### Method
GET

### Endpoint
/api/users/current

### Response
#### Success Response (200)
- **user** (object) - The user object.
  - **eid** (string) - The user's ECS ID.
  - **display_name** (string) - The user's display name.
  - **email** (string) - The user's email address.
  - **last_name** (string) - The user's last name.
  - **first_name** (string) - The user's first name.
  - **type** (string) - The type of user account (e.g., 'STUDENT', 'INSTRUCTOR').

#### Response Example
```json
{
  "eid": "your-ecs-id",
  "display_name": "Taro Yamada",
  "email": "taro.yamada@example.com",
  "last_name": "Yamada",
  "first_name": "Taro",
  "type": "STUDENT"
}
```
```

--------------------------------

### List Assignments by Status

Source: https://github.com/youseiushida/kulms/blob/main/README.md

Retrieves a list of assignments filtered by status. Case-insensitive matching is used for status. 'OPEN' status indicates assignments that are currently available.

```python
open_assignments = client.assignments.list(status="OPEN")
```

--------------------------------

### Session Information API

Source: https://context7.com/youseiushida/kulms/llms.txt

API for retrieving information about the current Sakai session, useful for checking session validity.

```APIDOC
## GET /api/sessions/current

### Description
Retrieves information about the current user's session, including session ID, user details, and activity times.

### Method
GET

### Endpoint
/api/sessions/current

### Response
#### Success Response (200)
- **session** (object) - The session object.
  - **id** (string) - The unique identifier for the session.
  - **user_eid** (string) - The ECS ID of the user associated with the session.
  - **active** (boolean) - Indicates if the session is currently active.
  - **creation_time** (string) - The timestamp when the session was created.
  - **last_accessed_time** (string) - The timestamp of the last session access.
  - **max_inactive_interval** (integer) - The maximum inactive interval allowed for the session in seconds.

#### Response Example
```json
{
  "id": "session-abc123xyz",
  "user_eid": "your-ecs-id",
  "active": true,
  "creation_time": "2025-04-15T10:00:00Z",
  "last_accessed_time": "2025-04-15T10:30:00Z",
  "max_inactive_interval": 1800
}
```
```

--------------------------------

### KULMS CLI Authentication Refresh

Source: https://context7.com/youseiushida/kulms/llms.txt

Refresh the current authentication session for the KULMS CLI.

```bash
# セッションの更新
kulms auth refresh
```