syvain-metrics 0.0.360 → 0.0.367

package/README.md

@@ -1,7 +1,9 @@
 # syvain-metrics
 
-Command line tools for inspecting [Syvain Metrics](https://metrics.syvain.com/)
-experiments, folders, metric rows, metric metadata, and annotations.
+Command line tool for [Syvain Metrics](https://metrics.syvain.com/). It is built
+for agents and scripts: every command prints newline-delimited JSON on stdout,
+errors go to stderr with exit code 1, and experiments and folders can be
+addressed by slug or path instead of ids.
 
 ## Install
 
@@ -13,40 +15,76 @@ The package installs the `syvain-metrics` binary.
 
 ## Authenticate
 
-Create an API key from the Syvain Metrics dashboard, then log in:
+Create an organization API key in the Syvain Metrics dashboard, then either save
+it with a login or export it for the current shell:
 
 ```sh
-syvain-metrics auth login
-syvain-metrics auth status --human
+syvain-metrics auth login            # prompts for the key
+printf '%s' "$KEY" | syvain-metrics auth login --stdin
+syvain-metrics auth status
+
+export SYVAIN_METRICS_API_KEY=ak_...   # skips the saved login
+export SYVAIN_METRICS_HOST=https://metrics.syvain.com   # optional override
 ```
 
-For scripts or CI, pass the API key on stdin:
+The CLI talks to `https://metrics.syvain.com` unless `--host` or
+`SYVAIN_METRICS_HOST` says otherwise.
+
+## Addressing things
+
+- An **experiment** is its id or its slug: `experiment get mamba-run-001`.
+- A **folder** is its absolute path or its id: `/models/mamba`. The root is `/`.
+  Paths are derived from the organization tree, so names with spaces work when
+  quoted.
+
+## Folders
 
 ```sh
-printf '%s' "$SYVAIN_METRICS_API_KEY" | syvain-metrics auth login --stdin
+syvain-metrics folder list                 # every folder with its path
+syvain-metrics folder list /models         # direct children of one folder
+syvain-metrics folder create /models/mamba # creates missing parents; idempotent
+syvain-metrics folder move /scratch/run-1 /models
+syvain-metrics folder move /scratch/run-1 /      # to the root
+syvain-metrics folder rename /models/mamba mamba-v2
 ```
 
-By default the CLI talks to `https://metrics.syvain.com`.
+`folder create` prints the leaf folder with `created: true` when it was made and
+`created: false` when the path already existed.
+
+## Experiments
+
+```sh
+syvain-metrics experiment list --search mamba      # id, slug, folderId, folderPath
+syvain-metrics experiment list --folder /models    # direct members only
+syvain-metrics experiment get mamba-run-001        # status, timestamps, meta, folderPath, url
+syvain-metrics experiment move mamba-run-001 /models/mamba
+syvain-metrics experiment catalog mamba-run-001    # series names with metadata keys and values
+syvain-metrics experiment annotations mamba-run-001 --limit 20
+```
+
+## Series
+
+`series query` prints one line per experiment, series, and metadata partition:
+`{experimentId, seriesName, metadata, data: {step, timestampMs, value}}`.
+Without `--name` it reads every series in the experiment's catalog.
+
+```sh
+syvain-metrics series query mamba-run-001 --name loss --filter split=valid
+syvain-metrics series query mamba-run-001 > run-001.jsonl
+syvain-metrics series query run-a run-b --name loss --x-axis timestamp
+```
 
-## Usage
+For analysis across many experiments prefer the
+[DuckDB extension](../../libs/metrics_duckdb/README.md); the CLI is the quick
+way to pipe one experiment into a file.
 
-The default output is newline-delimited JSON so commands can be piped into
-automation. Add `--human` for readable tables.
+`series render` charts the same selections as a PNG through the public Metrics
+Renderer. Every experiment, series, and metadata partition becomes one line, so
+use `--filter` to narrow what is drawn.
 
 ```sh
-syvain-metrics folders list --human
-syvain-metrics folders create --name dendro-mamba
-syvain-metrics experiments list --limit 20 --human
-syvain-metrics experiments get --slug dendro-mamba-run-001
-syvain-metrics experiments metrics --id exp_123 --metric-name loss
-syvain-metrics experiments query metric-series \
-  --series '{"experimentId":"exp_123","metricName":"loss","metadataFilter":[{"key":"split","value":"\"train\""}]}'
-syvain-metrics experiments render metric-series \
-  --series '{"experimentId":"exp_123","metricName":"loss","metadataFilter":[{"key":"model","value":"\"small\""}],"splitKeys":["data_split","curriculum_split"]}' \
-  --output metrics.png
-syvain-metrics experiments query metric-catalog --experiment-ids exp_123,exp_456
-syvain-metrics experiments annotate --id exp_123 --annotation "Good validation run"
+syvain-metrics series render run-a run-b --name loss --filter split=valid -o loss.png
+syvain-metrics series render run-a --name loss --display-mode subplots -o loss.png
 ```
 
-Run `syvain-metrics --help` or `syvain-metrics <command> --help` for the full
-command list and options.
+Run `syvain-metrics --help` or `syvain-metrics <command> --help` for every flag.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "syvain-metrics",
-	"version": "0.0.360",
+	"version": "0.0.367",
 	"description": "Syvain Metrics command line interface.",
 	"repository": {
 		"type": "git",
@@ -15,11 +15,11 @@
 		"syvain-metrics": "bin/syvain-metrics.js"
 	},
 	"optionalDependencies": {
-		"syvain-metrics-linux-x64": "0.0.360",
-		"syvain-metrics-linux-arm64": "0.0.360",
-		"syvain-metrics-darwin-x64": "0.0.360",
-		"syvain-metrics-darwin-arm64": "0.0.360",
-		"syvain-metrics-windows-x64": "0.0.360",
-		"syvain-metrics-windows-arm64": "0.0.360"
+		"syvain-metrics-linux-x64": "0.0.367",
+		"syvain-metrics-linux-arm64": "0.0.367",
+		"syvain-metrics-darwin-x64": "0.0.367",
+		"syvain-metrics-darwin-arm64": "0.0.367",
+		"syvain-metrics-windows-x64": "0.0.367",
+		"syvain-metrics-windows-arm64": "0.0.367"
 	}
 }