Dashboards and reports in the CLI

Q: Can I hand-edit queryText or the filter definitions?

Yes — the textual fields ( queryText , columnDefinitions , filterDefinitions , page size, format) are the most hand-editable part of these files and diff beautifully. The XML payloads are where caution applies: they are the designers' persistence formats, and a structurally broken edit surfaces as a designer error rather than a push error. Change them mechanically (a renamed field reference) or through the designer.

Q: What is the difference between the two dashboardType values?

DataStudio dashboards are built in the interactive dashboard designer over data models; Sql dashboards are driven by a query. The CLI treats both identically — the type rides along in the file — but knowing which you are looking at explains which fields carry the substance ( layoutDefinition for the former, the query for the latter).

xmatix dashboards and xmatix reports round-trip analytics definitions — including the embedded designer XML payloads that hold a dashboard's layout and a banded report's design — as one JSON file per artifact. Files carry the complete server row, not a trimmed summary, so server-only fields survive a pull → edit → push cycle untouched.

xmatix dashboards list
xmatix dashboards pull                # → xmatix/analytics/dashboards/<name>.json
xmatix dashboards pull <name-or-id>
xmatix dashboards push <file.json>    # update if the id resolves, create otherwise
xmatix dashboards push <file.json> --new

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

File shape

Each file is the full definition row, so everything the designers persist is present:

Dashboards — layoutDefinition (the dashboard designer's XML), settings, filterDefinitions, dashboardType (DataStudio or Sql), folder, icon, sortOrder, isActive.
Reports — queryText, columnDefinitions, filterDefinitions, defaultPageSize, reportFormat, compactWidth, and designLayoutXml (the banded-report designer's layout) for banded reports.

The XML payloads are large and designer-owned; treat them the way you treat a workflow's activity tree — reviewable as a diff, editable by hand only for mechanical changes, with the in-product designer as the real editor.

Push semantics

pull first enumerates ids from the dashboards and reports listings, then fetches each artifact's complete row individually — which is why the files are full-fidelity.
push updates when the file's id still exists on the server and creates otherwise; --new forces a create even when the id matches (the copy-to-another-tenant case).
Before sending, the CLI strips read-only audit columns and the visibility/ACL navigation collections, so the request matches what the server accepts.

Visibility does not round-trip yet. Who can see a dashboard or report — roles, profiles, teams, "all users" — lives in separate access-control tables and is not carried by these files. After creating an artifact on a new tenant via push, set its visibility in the product; this is planned for a future phase.

Common questions

My pushed dashboard is invisible to everyone — why?

Because visibility is not part of the file. A freshly created dashboard or report has no access grants until someone assigns them in the product — the definition arrived intact; the audience did not. This bites hardest in tenant-to-tenant promotion: budget a manual visibility pass (or a checklist entry) after the first push of each artifact.

Can I hand-edit queryText or the filter definitions?

Yes — the textual fields (queryText, columnDefinitions, filterDefinitions, page size, format) are the most hand-editable part of these files and diff beautifully. The XML payloads are where caution applies: they are the designers' persistence formats, and a structurally broken edit surfaces as a designer error rather than a push error. Change them mechanically (a renamed field reference) or through the designer.

What is the difference between the two dashboardType values?

DataStudio dashboards are built in the interactive dashboard designer over data models; Sql dashboards are driven by a query. The CLI treats both identically — the type rides along in the file — but knowing which you are looking at explains which fields carry the substance (layoutDefinition for the former, the query for the latter).