dashctl

Warning

This utility is designed for advanced users with specific niche workflows involving specific Axiom APIs. Most Axiom customers will not need this tool. It uses undocumented endpoints that may change without notice. Always copy important dashboards before making changes.

Small Bun-based CLI and linter for working with Axiom dashboards.

Introduction

Requirements

• Bun 1.2+ installed

Installation

bun install

Environment

• AXIOM_API_URL: e.g. https://app.axiom.co/api
• AXIOM_API_TOKEN: API token
• AXIOM_ORG_ID: organization id (header). The CLI sends both X-Axiom-Org-Id and X-Axiom-Organization-Id.

CLI: dashctl.js

• Endpoints: uses /internal/dashboards
• Output: prints JSON to stdout unless noted

Commands

• getAll [--summary]: List all dashboards (paginated). With --summary, prints id<TAB>name per line.
• get <id>: Print a single dashboard JSON by id.
• copy <id>: Clone a dashboard (GET → scrub server fields → POST). Prints id<TAB>name for the new dashboard.
• findAndReplace <id> --find <str> [--replace <str>] [--regex] [--dry-run] [--no-lint]
  • Replaces only within each chart’s query: query.apl and query.queryOptions.editorContent.
  • --dry-run prints the would-be payload without PUT.
  • If --replace is omitted, you can provide the replacement as the last positional arg.
  • --no-lint skips client-side validation.
• create <path-to-json> [--no-lint]: Create a new dashboard from a JSON file. Prints the new id (or JSON if id is missing).
• lint [--id <id> | <path-to-json>] [--strict]: Lint a dashboard by id (fetches it) or a local JSON file. --strict treats warnings as errors.

Examples

• Summaries: AXIOM_API_URL=… AXIOM_API_TOKEN=… AXIOM_ORG_ID=… bun run dashctl.js getAll --summary
• Get: … bun run dashctl.js get <id>
• Copy: … bun run dashctl.js copy <id>
• Dry-run replace: … bun run dashctl.js findAndReplace <id> --find "old" "new" --dry-run
• Create: … bun run dashctl.js create ./dashboard.json
• Lint by id: … bun run dashctl.js lint --id <id>
• Lint a file: bun run dashctl.js lint ./dashboard.json

Linter: src/lint-put.ts

• Validates PUT/POST payloads against real-world shapes (see examples/asa.json).
• Run directly: bun run src/lint-put.ts path/to/dashboard.json or pipe with -.
• Exit codes: 0 OK, 1 errors, 2 usage/parse issues.
• Strictness: warns for unknown chart types and flexible time windows; requires layout↔charts mapping, integers where appropriate, and version for PUT. Use --no-lint with CLI to bypass when necessary.

Spec

• dashboards-internal.json: a more realistic OpenAPI 2.0 spec for /internal/dashboards, derived from real-world Axiom dashboards.

Notes

• findAndReplace only touches chart query text; other fields are left unchanged.
• The CLI attempts to parse responses as JSON regardless of content-type and falls back to raw text on parse errors.

More about dashctl

While Axiom's internal dashboard APIs provide the programmatic access needed for bulk operations like dataset migrations and dashboard modifications, working directly with these endpoints can be challenging and risky. The APIs lack comprehensive documentation, and the existing OpenAPI specification doesn't fully match the implementation, making it easy to create malformed requests that could break dashboards or even corrupt the dashboard list entirely.

To address these challenges, we've developed dashctl, a command-line tool that provides a safer, more reliable interface for working with Axiom's internal dashboard APIs. Rather than requiring you to craft raw API requests, dashctl offers validated operations with built-in safeguards and a more accurate understanding of the dashboard data structure.

A safer approach to dashboard operations

dashctl acts as an augmented OpenAPI client, built from analysis of real dashboard data rather than incomplete specifications. The tool includes a comprehensive linter that validates dashboard structures before making API calls, helping prevent the kinds of errors that can break dashboard rendering or corrupt your dashboard collection. This validation layer catches common issues like missing required fields, invalid chart configurations, and layout inconsistencies before they reach Axiom's servers.

The tool requires three environment variables for authentication: AXIOM_API_URL (typically https://app.axiom.co/api), AXIOM_API_TOKEN (your API token with relevant dashboard-related permissions), and AXIOM_ORG_ID (your organization identifier). Once configured, dashctl provides several key operations designed specifically for dashboard management workflows.

Core operations for dashboard management

The getAll command retrieves all dashboards in your organization, with an optional --summary flag that provides a clean tab-separated list of dashboard IDs and names. This summary format is particularly useful for scripting and identifying dashboards that need attention. The get command fetches a specific dashboard by ID, returning the complete dashboard configuration as JSON.

For creating safe copies of dashboards before making changes, the copy command clones an existing dashboard, automatically handling the removal of server-managed fields and appending "(copy)" to the dashboard name. This is invaluable when you want to experiment with changes while preserving the original dashboard.

The findAndReplace command is specifically designed for the kind of dataset migration work you're undertaking. It safely replaces text within dashboard queries, operating only on the APL query content and editor content fields where dataset references typically appear. The command includes regex support for complex pattern matching and a --dry-run flag that shows you exactly what changes would be made without actually applying them. All replacements are validated through the built-in linter before being sent to the API.

For creating entirely new dashboards from JSON files, the create command handles the complexities of preparing dashboard payloads for the API, automatically removing server-managed fields and validating the structure before submission.

Built-in validation and safety features

Every operation that modifies dashboards includes automatic validation through dashctl's linter, which understands the real-world structure of Axiom dashboards. The linter recognizes various chart types including TimeSeries, Statistic, Table, Pie, LogStream, SmartFilter, Note, and MonitorList, and validates that each chart has the appropriate query structure for its type. It checks layout configurations, ensures proper field types, and validates cross-references between charts and layout items.

The validation system distinguishes between errors that will prevent dashboard functionality and warnings about non-critical issues. You can bypass validation with the --no-lint flag when necessary, though this should be used cautiously. For stricter validation during testing, the --strict flag treats warnings as errors.

Recommended workflow for dataset migration

When performing dataset migrations, we recommend starting with the getAll --summary command to identify your dashboards, then using copy to create safe duplicates of any dashboards you plan to modify. Use findAndReplace with the --dry-run flag first to preview changes, ensuring the replacements target the correct dataset references. Once you're confident in the changes, remove the --dry-run flag to apply them.

The lint command can validate existing dashboards or JSON files independently, helping you understand potential issues before making modifications. This is particularly useful for identifying dashboards that might have structural problems that could complicate migration efforts.

Important limitations and cautions

While dashctl provides significantly more safety than working directly with the internal APIs, it's important to remember that these are still experimental, undocumented endpoints. Axiom cannot restore previous dashboard versions, so creating copies of important dashboards before making changes is essential. The tool focuses on the most common dashboard operations and may not handle every edge case or newer dashboard features that weren't present in the training data.

We recommend starting with non-critical dashboards to familiarize yourself with the tool's behavior, and always using the --dry-run flag to preview changes before applying them. While the linter catches many potential issues, it's based on observed patterns rather than official specifications, so some validation may be overly permissive or restrictive in edge cases.

dashctl represents a pragmatic solution for working with Axiom's internal APIs while we develop more comprehensive public API support. It provides the programmatic access needed for bulk operations like dataset migration while offering meaningful protection against the kinds of errors that can disrupt dashboard functionality.