Dashboards as code

Overview

Every Osuite dashboard is a JSON document. The osuite dashboard CLI pulls those documents to local files, previews changes, and applies them back to the platform. This lets you review a dashboard in a pull request and commit it to source control like any other config, instead of only clicking it together in the UI.

Local JSON files are the source of truth. You edit the files; the CLI reconciles them with the remote state.

The CLI is installed as part of the one-time agent setup.

The three commands

osuite dashboard pull             # fetch all dashboards to the current directory
osuite dashboard plan [path]      # preview what would change
osuite dashboard apply [path]     # apply local files to the platform

pull

osuite dashboard pull fetches every dashboard from the platform and writes each one to a JSON file in the current directory, named after the dashboard. On later pulls it reconciles the remote state with your local files: unchanged files are left alone, remote-only changes are written down, and if a file has local edits and the remote changed, the two are merged with a three-way merge. A merge conflict is written into the file for you to resolve, opening $EDITOR if it is set.

plan

osuite dashboard plan [path] compares your local files to the platform and prints what apply would do, without changing anything. Each dashboard is reported as one of:

• create — a local file with no id, or an id not found on the platform.
• update — an existing dashboard whose local file differs from the platform.
• no-change — already in sync.
• needs-pull — the remote changed since you last pulled; run pull to merge before applying.

If [path] is omitted, every *.json file in the current directory is used. You can also pass a single file or a directory.

apply

osuite dashboard apply [path] writes your local files to the platform. Dashboards without an id are created — and the assigned id is written back into the local file — while dashboards with an id are updated. Unchanged dashboards are skipped.

Preview first with --dry-run:

osuite dashboard apply --dry-run
osuite dashboard apply ./dashboards/
osuite dashboard apply my-dashboard.json

If any dashboard is in the needs-pull state, apply refuses to run and tells you to pull first, so a concurrent edit in the UI is never silently overwritten.

A git workflow

osuite dashboard pull
git add .
git commit -m "Snapshot dashboards"

# edit a dashboard JSON file, then:
osuite dashboard plan
osuite dashboard apply --dry-run
osuite dashboard apply
git commit -am "Update service dashboard"

Because the files are plain JSON, dashboards diff cleanly in review. Keep them in a directory in your repo and treat apply as the deploy step.

File discovery and validation

• A JSON file is treated as a dashboard only if it has a name field; other JSON files in the directory are skipped with a warning.
• Before contacting the platform, plan and apply validate each file locally — every widget must have a valid chart_type, the required layout fields, and a queries array, and widget width must be within the 24-column grid. Invalid files fail before anything is sent.
• Never set id on a new dashboard (the platform assigns it) and never change the id of an existing dashboard or widget.

The full structure is documented in the dashboard JSON schema.

JSON output

Add the global -o json flag for machine-readable output, useful in CI:

osuite -o json dashboard plan
osuite -o json dashboard apply

Let an agent do it

The Visualizer Agent drives exactly this workflow. Its osuite-edit-dashboard skill reads and writes the same JSON files, runs osuite dashboard plan to show you the change, and runs osuite dashboard apply once you approve — so you can generate and apply a dashboard from a plain-English request without hand-editing JSON.

Next steps

• Dashboard JSON schema — the fields you edit
• Dashboard builder — the UI equivalent
• Visualizer Agent — generate and apply dashboards from natural language