kater rename

Renames a field or an object in every place that names it, in every folder, as one change.

Without --write it shows the preview and changes nothing. Name what to rename by the natural key that a field’s card shows, by an object’s key, or by the path of its file.

Examples

# See every place a rename of a shared field changes
kater rename semantic.marketing_sessions.sessions session_count
# Rename it
kater rename semantic.marketing_sessions.sessions session_count --write
# Bring the rename to your local copy
kater git pull

Arguments

Argument Description

<key-or-path> What to rename. A field by its natural key: semantic.<model>.<field>, kater_dataset.<dataset>.<field>, workspace.<workspace>.<field> or query.<query>.<field>. An object by its key: query.<name>, chart.<name>, workspace.<name>, semantic.<name>, kater_dataset.<name> or insight_template.<name>. A workspace’s parameter or filter: workspace.<workspace>.<name>, and a Sandbox file’s: <file>.sql#<name>. Or a path, for an app, an app page, a project and its metrics, a workflow, an agent, a skill and a schedule: an app’s kater.app.yaml, an app page’s .html file, a project’s kater.project.yaml (add #<metric> for one of its metrics), a workflow’s workflow.md, an agent’s or a skill’s .md file, or a schedule’s .yaml file.

<new-name> The new name: lower case letters, digits and underscores, starting with a letter. A workflow, an agent, a skill, a schedule and an app page also take hyphens.

Argument	Description
`<key-or-path>`	What to rename. A field by its natural key: `semantic.<model>.<field>`, `kater_dataset.<dataset>.<field>`, `workspace.<workspace>.<field>` or `query.<query>.<field>`. An object by its key: `query.<name>`, `chart.<name>`, `workspace.<name>`, `semantic.<name>`, `kater_dataset.<name>` or `insight_template.<name>`. A workspace’s parameter or filter: `workspace.<workspace>.<name>`, and a Sandbox file’s: `<file>.sql#<name>`. Or a path, for an app, an app page, a project and its metrics, a workflow, an agent, a skill and a schedule: an app’s `kater.app.yaml`, an app page’s `.html` file, a project’s `kater.project.yaml` (add `#<metric>` for one of its metrics), a workflow’s `workflow.md`, an agent’s or a skill’s `.md` file, or a schedule’s `.yaml` file.
`<new-name>`	The new name: lower case letters, digits and underscores, starting with a letter. A workflow, an agent, a skill, a schedule and an app page also take hyphens.

Options

Option	Description
`--to <to>`	Move a query to another workspace of its connection, by the workspace’s folder from the content root, as a rename of its path. Its charts move with it. Give its name now as NEW_NAME to keep it. Only a query moves.
`--write`	Rename it. Without it, the command shows the preview and changes nothing.

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

The preview

Each place that you can open, by folder, file and line, with the line as it reads after the rename and the new name marked.
What moves. A query’s file and a workspace’s folder, with its dashboard and its grants, take the new name.
The places in folders that you cannot open, as a count only. Kater writes them for you.
What keeps its words, such as a label or a name that the field picker made.
A name that is taken stops the rename. Kater shows it in red, then “Nothing changed.”

What it answers

With --write it gives the files it changed and the change’s id. kater undo with that id takes the whole rename back.

A query or a chart named without its workspace is found in the workspace that you work in, then in every workspace that you can open. When two have that name, give its path.
Something that you cannot open is not found, as for something that does not exist.
A rename that changes other people’s folders is written by Kater’s worker. The command waits for it and says so.
Agents ask first. An agent shows you the preview, and runs --write with kater_apply only after you say yes.
In your own terminal, it renames in Kater, so it needs kater login. kater git pull brings the rename to your local copy.