Kater CLI › Make and compare › new
kater new project
Make a project in your own projects folder, in one commit.
--start selects its type: target, test or launch, with that type’s choices. Show the project to the person and make it only after they say yes. Its first timeline row tells why it starts: --asked, then --why.
Examples
# Make a project in your own projects folder, in one commitkater new project <name>Arguments
| Argument | Description |
|---|---|
<name> | The project’s title in words, such as “Paid Social conversion”, or its folder name, such as paid_social_conversion. The folder takes its name from the title, so with --title, Kater makes the folder name from --title. |
Options
| Option | Description |
|---|---|
--goal <goal> | One sentence that says what the project is for. With --start launch, the launch it follows, such as The spring sale. Left out with --start, Kater writes it from the type’s choices: Get <metric> to <target> by <end date>. |
--title <title> | The project’s title, as the page shows it, such as Paid Social conversion. Left out, it is NAME in words: Paid social conversion. |
--asked <asked> | The question the project starts from, in the words of the person who asked it, such as “Why did Paid Social drop?”. The timeline shows it first on the project’s first row. |
--app <app> | An app the project groups, by its id. Give it once for each app. You can give it more than one time. |
--workspace <workspace> | A workspace the project groups, by its full path. Its dashboard gets a snapshot each week. Give it once for each workspace. You can give it more than one time. |
--query <querie> | A query the project groups, by its workspace’s full path and its name. Give it once for each query. You can give it more than one time. |
--chart <chart> | One chart of an app, in place of the whole app, as APP:QUERY: the app’s id, a colon, and the query its page draws there, such as app_<id>:…/workspaces/web_orders_weekly/conversion_by_channel. Give it once for each chart. You can give it more than one time. |
--starts <starts> | Start date: when the project starts, such as 2026-10-05. |
--ends <ends> | End date: when the project ends, such as 2026-11-30. With none, it runs until you close it, or with --start test, until its readout. |
--metric <metric> | A number the project is judged by, as <query>.<field>[:<row key>][=<name>], such as …/conversion_by_channel.conversion_rate:Paid Social. Left out, its name is the row key and the field’s label in the query: Paid Social Conversion rate. The first is the goal’s, which --target sets. Kater reads each one’s weeks at once. You can give it more than one time. |
--attach <attach> | Context: a file the project keeps, by the id PUT /v1/timeline/uploads answered (att_…), or by its content path, which Kater copies. 10 MB at most: PNG, JPEG, WebP, GIF, PDF, CSV, JSON, XLSX, DOCX, PPTX, text or Markdown. Give it once for each file. You can give it more than one time. |
--link <link> | Context: an https: address, or a Kater page’s address that starts with /, such as /app/<app id>. Give it once for each link. You can give it more than one time. |
--capture <capture> | Context: a picture of a Kater page, by its portal address, such as /app/<app id>/viewing?tab=index&slide=3 or /workspace/<path>?view=dashboard. The worker takes it as you see the page. Give it once for each page. You can give it more than one time. |
--from <made-from> | The entry the project is made from, such as app_…/2026-10-05-snapshot. |
--why <why> | What Kater found and what the project follows, in two or three short sentences with the key figures, such as “Kater found that Paid Social’s conversion rate fell from 3.1% to 1.8% in two weeks, while its visits stayed the same. This project follows its conversion rate until it is back above 3% or Nov 30.” The timeline shows it on its first row, after --asked. |
--start <start-type> | The type to start from: target, test, launch. Left out: a plain page. |
--target-value <start-target-value> | Target. A number, such as 2.20. For target. |
--source <start-source> | Source data. Kater selects the source data that fits what you write. Or select one or more you know. A dashboard, a query, a shared model or an app, by its path from the content root. Give it once for each. Left out, Kater finds the best fit. You can give it more than one time. |
--decision <start-decision> | Change. For test. |
--readout-weeks <start-readout-weeks> | Readout. When Kater compares the numbers after the change with the numbers before it. Takes 2 (After 2 weeks), 4 (After 4 weeks), 8 (After 8 weeks). Left out: 4, unless the type sets its own. For test. |
It also takes the global options --json and --help.