Dashboards and reports in the CLI

Q: Can I still use the CLI to move a dashboard to another tenant?

Not in the current release. push cannot create or update a dashboard or report, with or without --new , because the server refuses the collection name it uses. Recreate the definition in the target tenant's designer and set its visibility there. Then use list in that tenant, signed in as a user who should see it, to confirm that it is active and visible. The rest of a tenant's configuration can still travel through the CLI. Metadata, scripts, rules and workflows have their own pull and push commands, and snapshots and migrations run them for you.

Q: Why does pull exit 0 when nothing was written?

pull treats a failure on one definition as a per-row problem. It prints the failure and continues with the rest, and its exit code reflects only failures before that loop, such as a failed list request. A pipeline that has to notice an empty pull should check the Pulled N line or the folder contents, not the exit code. The simplest safe setup is to skip both kinds in automated jobs.

xmatix dashboards and xmatix reports are the CLI's commands for analytics definitions. list shows the dashboards or reports your account can see. pull and push are meant to round-trip each definition as one JSON file, but in the current CLI release the server refuses both, so no analytics file is ever written or sent. Build and change dashboards and reports in the product's designers, and leave them out of CLI snapshots with --skip dashboards,reports.

Overview

The commands sit alongside the other artifact kinds in the CLI (see the command map):

xmatix dashboards list
xmatix dashboards pull [<name-or-id>]       # → xmatix/analytics/dashboards/<name>.json
xmatix dashboards push <file.json> [--new]

xmatix reports list
xmatix reports pull [<name-or-id>]          # → xmatix/analytics/reports/<name>.json
xmatix reports push <file.json> [--new]

Command	What happens today
`dashboards list`, `reports list`	Works. Prints a table of Name, Label, Folder, Active and Id, then a count.
`dashboards pull`, `reports pull`	Lists the definitions, then fails on each one with a 404 and writes no file. The command still exits 0 and reports `Pulled 0 …`.
`dashboards push`, `reports push`	Fails with `Push failed:` and a 404, and exits 1. Nothing is created or changed.

When to use it

Use list to get a quick inventory of the dashboards or reports a user can see, with their ids and folders. One example is checking that a dashboard reached a tenant after someone built it in the product.
Do not rely on pull or push to version, review or promote analytics definitions. They move nothing in the current release. Keep dashboards and reports in the product designers, and keep scripts, rules, workflows and metadata under source control with the CLI.

How xMatix handles it

What list shows

list asks the server for the same catalogue the product's lists use. That catalogue holds only active definitions that the signed-in identity can see: the ones it created, the ones assigned to its roles, profiles or teams, and the ones shared with it or with all users. Definitions that the tenant's licence doesn't cover are removed. For dashboards the catalogue covers the Dashboards area only. Dashboards that belong to the Analytics area under Data Studio are not listed. Rows are sorted by Name.

So list is one user's view, not a tenant-wide inventory. An inactive dashboard, or one that has not been shared with you, is missing from the output even though it exists.

Why pull and push fail

After listing, pull fetches each definition's complete row through the generic metadata API under the collection names Dashboard and Report. The server stores the definitions under different collection names, so it answers each request with 404 — Unknown metadata collection ("There is no metadata collection named 'Dashboard'."). pull prints the failure next to each definition's name and moves on, so it ends with Pulled 0 dashboard(s) and exit code 0.

push first checks whether the file's id exists by using the same collection name. That check fails, so the CLI treats the definition as new and sends a create request, which the server refuses in the same way. The CLI prints Push failed: POST metadata/Dashboard returned 404: … (or metadata/Report) and exits 1. --new only skips the existence check, so it ends the same way.

What a file would contain

The CLI would write each definition's complete row, so a file you write by hand or keep from elsewhere has this shape. These are the fields the server stores:

Dashboards — name, label, description, folder, icon, sortOrder, isActive, dashboardType (Data Studio or SQL), surface (Dashboards or Analytics area), layoutDefinition, settings and filterDefinitions. A Data Studio dashboard keeps its designer XML in layoutDefinition. A SQL dashboard keeps a JSON widget-and-grid definition in the same field.
Reports — name, label, description, folder, icon, sortOrder, isActive, queryText, columnDefinitions, filterDefinitions, defaultPageSize, reportFormat, compactWidth, source, sourceObjectName and, for banded reports, designLayoutXml.

Before sending, push strips the id, the audit columns (created and modified by and when) and the visibility and sharing collections. Visibility is not carried by these files: roles, profiles, teams and "all users" access is always set in the product.

Prerequisites

A workspace and a signed-in session (xmatix init, xmatix login). See Authentication.
For a meaningful list, sign in as a user who can see the dashboards or reports you are interested in. The list is filtered to that user.

Procedure

Step 1 — List what a user can see

Run xmatix dashboards list or xmatix reports list. You see a table with Name, Label, Folder, Active ("yes" or "no") and Id, followed by a line such as 12 dashboard(s). Every row shows Active "yes", because the catalogue holds only active definitions.

Step 2 — Keep analytics out of snapshots

Add --skip dashboards,reports to xmatix snapshot export and xmatix snapshot import. Export then pulls metadata, scripts, rules and workflows only. Import stops sending the analytics folders, which would otherwise count every analytics file as a failure. See Snapshots.

Step 3 — Exclude the folders from watch

If you use xmatix watch, start it with --no-dashboards --no-reports so a save in an analytics folder doesn't start a push that is bound to fail.

Step 4 — Make analytics changes in the product

Create and edit dashboards and reports in the product's designers, then set who can see each one there. Run list afterwards (Step 1), signed in as a user who should see the definition, to confirm it is active and visible.

Example

A team keeps its tenant's automation in a repository and promotes it from a test tenant to the live tenant. Its nightly drift job runs:

xmatix doctor
xmatix snapshot export --skip dashboards,reports
git status --porcelain

Its release job runs xmatix snapshot import --skip dashboards,reports. A reviewer builds the new "Weekly collections" dashboard by hand in the live tenant's designer and shares it with the collections team. They then sign in to the CLI as a collections user and run xmatix dashboards list. The new row shows Folder "Finance", Active "yes" and its id, which confirms that the collections team can see the dashboard.

Training

Practice exercise

In a sandbox workspace, run xmatix dashboards list and note one dashboard's name. Run xmatix dashboards pull "<that name>". Expected result: the output shows a red cross next to the name with a 404 for metadata/Dashboard, ends with Pulled 0 dashboard(s), and xmatix/analytics/dashboards/ holds no new file. Then run xmatix snapshot export --skip dashboards,reports and confirm that it ends with "Snapshot export complete."

Quick reference

list works; pull and push are refused by the server in the current release.
list shows active definitions the signed-in identity can see, not every definition in the tenant.
The dashboards list covers the Dashboards area only, not Analytics under Data Studio.
pull exits 0 even when it writes nothing, so read its Pulled N line.
push exits 1 with Push failed: and a 404.
Use --skip dashboards,reports on snapshot export and import, and --no-dashboards --no-reports on watch.
Visibility is never carried by these files; set it in the product.

Permissions

list needs only a signed-in session; what it returns depends on what the signed-in user can see (see How xMatix handles it). pull and push go through the metadata API, which is open only to users with setup rights; a user without them is refused with a 403 instead of the 404. Either way, no identity can complete a pull or push. Authoring dashboards and reports in the product, and setting their visibility, follows the product's own analytics and security permissions.

Common problems

`pull` says "Pulled 0" and shows a 404 for every dashboard or report

This is the current behaviour of pull, described in Why pull and push fail. No configuration on your side changes it. Keep the analytics kinds out of snapshots with --skip dashboards,reports.

`snapshot export` reports success but the analytics folders are empty

dashboards pull and reports pull exit 0 even when every definition fails, so the export counts them as successful. Look in the export output for the per-definition failures. Skip both kinds so the output reflects only what was really exported.

`snapshot import` or `migrate apply` exits non-zero on analytics files

Each analytics file you push fails, and the import counts every failure. Remove the files from xmatix/analytics/, or add --skip dashboards,reports to the import.

`migrate plan` lists every analytics file as added

The plan compares your folders with a fresh server export, and that export contains no analytics files. Every local analytics file therefore appears as "local only — push will create", although the push would fail. Remove the files or skip the kinds.

A dashboard I know exists is missing from `list`

The list shows only active definitions that the signed-in identity can see. For dashboards it covers the Dashboards area only. Check that the definition is active and shared with that user, and whether it belongs to the Analytics area under Data Studio.

Common questions

Can I still use the CLI to move a dashboard to another tenant?

Not in the current release. push cannot create or update a dashboard or report, with or without --new, because the server refuses the collection name it uses. Recreate the definition in the target tenant's designer and set its visibility there. Then use list in that tenant, signed in as a user who should see it, to confirm that it is active and visible. The rest of a tenant's configuration can still travel through the CLI. Metadata, scripts, rules and workflows have their own pull and push commands, and snapshots and migrations run them for you.

Why does `pull` exit 0 when nothing was written?

pull treats a failure on one definition as a per-row problem. It prints the failure and continues with the rest, and its exit code reflects only failures before that loop, such as a failed list request. A pipeline that has to notice an empty pull should check the Pulled N line or the folder contents, not the exit code. The simplest safe setup is to skip both kinds in automated jobs.

What is the difference between the two dashboard types?

A Data Studio dashboard is built in the interactive dashboard designer, and its layoutDefinition holds the designer's XML. A SQL dashboard is built from query-backed widgets, and its layoutDefinition holds a JSON definition of those widgets and the grid. Separately, the surface field records whether the dashboard lives in the Dashboards area or the Analytics area under Data Studio, and only the Dashboards area is in the CLI list.