Skip to main content
DocumentationLibraryReference
On this page

Kater CLI Find and understand files

kater files add-to

Adds a query or a chart to a workspace, a dashboard, an app or the Sandbox.

It works as Add to on the Files page does, and also adds a page to an app. With no place named, it lists the places where the file can go.

Examples

Terminal window
# Go to the snowflake_prod_connection connection
cd connections/snowflake_prod_connection
# List the places where the spend_by_platform query can go
kater files add-to workspaces/ad_reporting/query_contracts/spend_by_platform.sql
# Open the query in a new scratch file in the Sandbox
kater files add-to workspaces/ad_reporting/query_contracts/spend_by_platform.sql --sandbox
# Copy the query into a new workspace of yours, named Spend review
kater files add-to workspaces/ad_reporting/query_contracts/spend_by_platform.sql --new-workspace --name "Spend review"
# Add the spend_mix chart to a new app of yours
kater files add-to workspaces/ad_reporting/charts/spend_mix.sql --new-app

Arguments

ArgumentDescription
<path>The file of a query or a chart in a workspace, or a page, which is an .html file. Give its path from the folder you are in, or from --kater-root.

Options

OptionDescription
--line <n>The line of the query to add, in a file that declares several. Lines count from 1. Leave it out to add the first query.
--workspace <path>Copies it into a workspace that reads the same shared model, by the workspace’s folder. See Where it can go.
--new-workspaceMakes a new workspace in your own folder for it. The new workspace starts from the root of the query’s workspace.
--dashboard <path>Puts a chart on a workspace’s dashboard, by the workspace’s folder.
--app <path>Adds it to one of your apps, by the app’s folder.
--new-appMakes a new app in your own folder for it.
--name <text>The name of the new workspace or app. Kater also names its folder from it, in lower case with underscores, with _2 added when that name is taken. Use it with --new-workspace or --new-app.
--sandboxOpens a new scratch file on the query, in your brainstorm folder. The file reads the query’s workspace by its full address.

It also takes the global options --json, --kater-root, --scope and --help.

Where it can go

  • A workspace. One of yours, or a connection workspace that you can change, that reads the same shared model. The query goes into its query_contracts/ under its own name, or with _2, _3 and on when that name is taken. When the query does not compile there, Kater refuses it with the compiler’s words. A chart brings its query.
  • A dashboard. This is for a chart only. Kater puts the chart on the dashboard’s first tab. When the workspace is not the chart’s own, Kater first copies the chart and its query there.
  • An app. A query goes at the end of the app’s first page as a <kater-table> tag. A chart goes there as the tag that draws its kind, with its fields. That tag is marked data-kater-chart, with the chart it came from. A page goes in as another page of the app.
  • A new app. A page becomes its index.html. Kater refuses a page that the app check would refuse.
  • The Sandbox. Kater opens a new scratch file on the query.

A new workspace or app without --name gets the name unnamed_workspace_ or unnamed_app_, with a number.

The list of places

With no place named, the list holds these places, each with the option that selects it:

  • The dashboard of the chart’s own workspace, and the dashboards of the workspaces it can go into.
  • Your own workspaces, and the connection workspaces you can change that read the same shared model.
  • A new workspace, your own apps, a new app and the Sandbox.

Someone else’s workspace or app is never in the list. Each place says whether it holds the query or chart already.

Through an agent

Outside a brainstorm folder, the kater tool of the Kater MCP refuses this change. An agent adds it with kater_apply after the person agrees.

See also