synology/CLAUDE.md

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):

   {
     "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)

python3 scripts/synology_api_login.py

Get system info with human-readable summary

python3 scripts/synology/api_login.py --system-info --summary

Get system info as compact JSON (for scripting)

python3 scripts/synology_api_login.py --system-info --json-compact

Using a profile from hosts.json

python3 scripts/synology_api_login.py --profile home-nas --system-info --summary

Direct credentials (overrides env vars)

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