# Studio (beta)

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

Studio templates are the pages, docs and other assets Kenso builds for each account or lead. The `kenso studio` commands let you edit a template as a folder of files on your machine, check it, preview it, and fill it for many accounts or leads at once. They are beta: they need the `studio` feature flag on your workspace. Help and `kenso describe` hide them until your workspace has it; `--all-commands` shows them.

| Command | What it does |
|---|---|
| `studio pull <templateId> --dir <dir>` | Write a template version's files to a folder |
| `studio push <templateId> --dir <dir>` | Save the folder's files to the template's draft and print the validation |
| `studio validate <templateId> --dir <dir>` | Validate the folder against the template without saving |
| `studio preview <templateId>` | Render a version for up to 3 accounts and print the preview links |
| `studio fill <templateId>` | Fill the template for many accounts or campaign leads, estimate first |

Find template ids with the generated commands:

```bash
kenso asset-templates list
```

## Edit a template locally

```bash
kenso studio pull 12 --dir ./my-template
kenso studio validate 12 --dir ./my-template
kenso studio push 12 --dir ./my-template
kenso studio preview 12 --dir ./my-template --account-ids 501,502
kenso studio push 12 --dir ./my-template --publish
```

### pull

`pull` writes every file of the version under `--dir`: text files from the answer, binaries downloaded from signed links and checked against their SHA-256. It overwrites files with the same path and leaves other files in the folder alone. It checks every path before it writes anything, and refuses one that would land outside `--dir` (`unsafe_path`).

`--template-version` picks the version: `draft`, `latest` (the latest published) or a version id. The default is the draft, else the latest published version. (The flag is not `--version`: after a command, `--version` fails with `unknown_flag` and points at `--template-version`.)

```bash
kenso studio pull 12 --dir ./v3 --template-version 345
kenso studio pull 12 --dir ./my-template --dry-run
```

It prints `{templateId, versionId, files, dir}`. `--dry-run` lists the paths and writes nothing.

### push

`push` reads `--dir`, skipping dotfiles, dot folders and `node_modules`.

- A text file (valid UTF-8, no NUL byte, under 1 MB) goes inline.
- Any other file is uploaded through a signed upload URL first, 4 at a time, up to 5 MB each. A larger file is refused before any call.
- One push then saves the files into the draft and prints `{templateId, versionId, versionNumber, validation, changed, deleted}`.

Files that are in the draft but not in the folder stay, unless you pass `--delete-missing`. `--message` describes the change (default "Pushed with the Kenso CLI"). With `--publish`, the new version is published when validation passes, and the output adds `published`.

```bash
kenso studio push 12 --dir ./my-template --message "New hero copy"
kenso studio push 12 --dir ./my-template --delete-missing --publish
kenso studio push 12 --dir ./my-template --dry-run
```

When validation finds errors, the draft is still saved: the result prints, then the error `validation_failed` (exit 2) with the first problem as its `hint`. When publishing fails after a good push, the push result still prints and the error says which version was saved. `--dry-run` lists what would be sent and calls nothing.

### validate

`validate` reads the folder the same way and checks the files laid over the draft, as a push would, without saving them. Binaries are uploaded so they can be checked. `--delete-missing` validates exactly the folder's files. It prints the validation and exits 2 when there are errors.

### preview

`preview` renders a saved version, not your local files: the draft, else the latest published version, or `--version-id`. It takes up to a minute per account.

```bash
kenso studio preview 12
kenso studio preview 12 --account-ids 501,502,503 --mode render
kenso studio preview 12 --sample samples/acme.json
kenso studio preview 12 --mode interact --interact @steps.json
```

- `--account-ids` takes up to 3 ids. Without it, Kenso picks the 3 most recently touched accounts, else the template's samples.
- `--mode` is `render` (default) or `interact`. `--interact` takes the click, type and wait steps as JSON, `@file` or `-` (up to 20).
- With `--dir`, the CLI compares your folder to the version it renders and warns on stderr when they differ, naming the push command to run first.

The output lists each preview's link, screenshots, console errors and link issues.

## Fill a template for many accounts or leads

`fill` creates pages for a list of accounts, or for the leads of a campaign. A fill is charged per page, so it always prices the work first.

```bash
kenso studio fill 12 --accounts accounts.txt
kenso studio fill 12 --accounts accounts.csv --column accountId --yes --wait
kenso studio fill 12 --campaign 345 --contacts leads.csv --yes
```

- **Ids** come from `--accounts <file>`, or from `--contacts <file>` with `--campaign <id>`; `-` reads stdin. A file holds one id per line, or a CSV or JSONL with an id column (`--column`, else `id`, else `contactId`). Repeated ids are filled once.
- **Without `--yes`** (or with `--estimate`) it prints the estimate and the apply command, and creates nothing. For a campaign, the estimate counts one page per lead; Kenso builds one page per company, so it is an upper bound.
- **With `--yes`** it creates one fill run per 500 ids, one after another.
- **With `--wait`** it follows each run every 5 seconds until it completes, fails or is cancelled. Without it, follow a run with `kenso asset-runs get --run-id <id>`.

The summary lists `runs: [{runId, state, rows}]`, and `results.csv` has one line per id with its page id and state.

**The same fill never runs twice.** Rebuilding a page charges again, so when you rerun a fill with the same file (the same bytes) and the same flags:

- an unfinished fill continues where it stopped;
- a finished fill where every id succeeded answers from that run and changes nothing;
- anything else is refused with `already_filled` (exit 7). To retry only the ids that failed, take them from the earlier run's `results.csv` into a new file and fill that file.

The guard compares the file and the flags, not the ids: the same ids in another file, or in another order, are filled and charged again. Keep one ids file per fill, and check `kenso runs list` before you fill ids from a new file.

## Other Studio commands

Everything else (create a template, list versions, restore a version, datasets, publish) is a generated command under `asset-templates`, `asset-runs` and `asset-template-datasets`:

```bash
kenso asset-templates --help --all-commands
kenso describe asset-templates
```

## More for developers

- [API docs](/docs)
- [MCP server](/mcp)
- [Interactive API reference](https://developer.ken.so/reference/)
- [Changelog](/docs/changelog)
