Timmy
321456d4e6
- Add synology_api.py: DSM API client library - Add synology_api_login.py: CLI tool for login and system info - Add SKILL.md: Skill definition with usage examples - Add CLAUDE.md: Developer documentation - Add references/: Example configs and usage guide Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
92 lines
2.9 KiB
Markdown
92 lines
2.9 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Overview
|
|
|
|
This is a Synology DSM API client library and CLI tool. It provides a Python interface to interact with Synology NAS via the WebAPI, supporting login, session reuse, and system information retrieval.
|
|
|
|
## Architecture
|
|
|
|
### Core Components
|
|
|
|
- **`scripts/synology_api.py`** - The `DSMApiClient` library class. Handles authentication, session management, and API calls. Uses only stdlib (urllib, ssl, json).
|
|
|
|
- **`scripts/synology_api_login.py`** - CLI wrapper that uses the library. Supports profile-based configuration, SID session caching, and system info retrieval with human-readable or JSON output.
|
|
|
|
### Session Management
|
|
|
|
The client caches SID sessions to avoid repeated logins:
|
|
1. On run, checks `tmp/synology_session.json` for a valid SID
|
|
2. If SID is still valid (probed via `get_system_info`), reuses it
|
|
3. Otherwise, performs full login and saves new session
|
|
|
|
### Configuration Methods
|
|
|
|
Two ways to configure credentials:
|
|
|
|
1. **Environment variables** (`.env` in workspace root):
|
|
```
|
|
DS_URL=https://syno.example.com/
|
|
DS_USER=username
|
|
DS_PASSWORD=password
|
|
```
|
|
|
|
2. **Profiles** (`references/hosts.json`):
|
|
```json
|
|
{
|
|
"profile-name": {
|
|
"url": "https://nas.local:5001",
|
|
"user": "username",
|
|
"password_env": "DS_PASSWORD_PROFILE"
|
|
}
|
|
}
|
|
```
|
|
Use with `--profile profile-name`
|
|
|
|
## Common Commands
|
|
|
|
### Basic login (with session caching)
|
|
```bash
|
|
python3 scripts/synology_api_login.py
|
|
```
|
|
|
|
### Get system info with human-readable summary
|
|
```bash
|
|
python3 scripts/synology/api_login.py --system-info --summary
|
|
```
|
|
|
|
### Get system info as compact JSON (for scripting)
|
|
```bash
|
|
python3 scripts/synology_api_login.py --system-info --json-compact
|
|
```
|
|
|
|
### Using a profile from hosts.json
|
|
```bash
|
|
python3 scripts/synology_api_login.py --profile home-nas --system-info --summary
|
|
```
|
|
|
|
### Direct credentials (overrides env vars)
|
|
```bash
|
|
python3 scripts/synology_api_login.py --url "https://192.168.1.10:5001" --user admin --password "xxx" --system-info
|
|
```
|
|
|
|
## Output Files
|
|
|
|
- `tmp/synology_api_login_result.json` - Login result metadata
|
|
- `tmp/synology_session.json` - Cached SID session
|
|
- `tmp/synology_system_info.json` - Full API responses bundle
|
|
|
|
## API Fallback Pattern
|
|
|
|
DSM versions vary in API support. The client uses `_try_api_candidates()` which tries multiple endpoint/version combinations and returns the first successful response. When adding new API methods, follow this pattern for compatibility.
|
|
|
|
## Compact JSON Schema
|
|
|
|
The `--json-compact` output normalizes across DSM versions and includes:
|
|
- `model`, `serial`, `ip` (prefers eth0)
|
|
- `dsm_version`, `cpu_usage_pct`, `cpu_clock_mhz`
|
|
- `memory_total_mb`, `memory_usage_pct`, `temperature_c`
|
|
- `volumes` (list), `disk_size_usage` (bytes + GiB), `disk_health`
|
|
- `time`, `uptime`
|