---

name: open-api-and-cli description: "Use SwanLab's object-oriented Api and swanlab api CLI for metadata, filters, runs, metrics, media, logs, and exports." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

SwanLab Open API and CLI

Use this sub-skill when the task is to read or manage SwanLab cloud/self-hosted metadata through swanlab.Api or the swanlab api command group.

Route here for

• swanlab.Api construction, credential-safe query patterns, entity factories, ApiResponseType, lazy entity .wrapper() calls, and JSON payload handling.
• User, workspace, project, run/experiment, self-hosted instance, and admin metadata queries.
• Project/run path validation, project-name validation, filters, groups, sorts, pagination, summaries, metric key listing, scalar metrics, media metrics, logs, and export URL flows.
• swanlab api ... --help and non-interactive CLI use with --host, --api-key, --save, paging flags, filter JSON, and range flags.

Route away

• Credential storage, swanlab login, mode selection, settings files, and host precedence belong to the settings-and-modes sub-skill.
• Creating experiment runs or logging scalars/media from training code belongs to the experiment-tracking or media-and-custom-charts sub-skills.
• Syncing local/offline run directories or converting TensorBoard/W&B/MLflow records belongs to the sync-and-converters sub-skill.

First reads

1. Read references/api-reference.md for the Python object model, path shapes, filters/sorts/groups, pagination, metrics, logs, CSV/export URL behavior, and self-hosted admin checks.
2. Read references/cli-reference.md for command names, common flags, JSON output, safe help checks, filter JSON, and non-interactive usage.
3. Read references/troubleshooting.md when a path, API key, host, HTTP status, filter query, pagination, self-hosted permission, or CLI automation problem appears.
4. Run scripts/check_api_validation.py after editing this sub-skill or when you need a no-network sanity check of the validation contracts.

Operating checklist

• Validate path shape before making remote calls: workspace is one segment, project is workspace/project, and run is workspace/project/run.
• Treat Api() construction and any entity property/wrapper/iterator as network-capable. Only CLI help and bundled validation helpers are intended to be safe without credentials.
• Prefer series(), metrics(), summary(), medias(), logs(), and export_logs() for current run data workflows. column() and columns() are deprecated compatibility surfaces.
• For CLI automation, use explicit arguments and flags; do not rely on prompts. Help commands are safe, but query commands need valid credentials and network access.