Kalpana Docs

@kalpana-one/cli gives you the kalpana command. It needs Node 20.3 or later.

npm install -g @kalpana-one/cli

pnpm add -g @kalpana-one/cli

yarn global add @kalpana-one/cli

bun add -g @kalpana-one/cli

Or run it without installing:

npx @kalpana-one/cli templates list

pnpm dlx @kalpana-one/cli templates list

yarn dlx @kalpana-one/cli templates list

bunx @kalpana-one/cli templates list

Log in

Create a key as described in Authentication, then:

kalpana login

The key is typed without echo, checked against the API and saved in ~/.config/kalpana/config.json, readable only by you. Its workspace becomes the default. kalpana whoami shows what is in use and kalpana logout forgets the key.

Find a template and its fields

kalpana templates list --search "product"
kalpana templates fields t4hz8c1n

FIELD       LAYER       KIND   DEFAULT
headline    Headline    text   Weekend offer
hero_image  Hero image  image  0b0f5a3e-...
background  Background  style

A field can be named by its id or its layer name. Colour fields are listed but cannot be set through the API yet.

Render one file

kalpana render t4hz8c1n \
  --set headline="Weekend offer" \
  --set "Hero image"=./shirt.jpg \
  --out offer.png

An image value can be a local file (uploaded for you), a URL (saved to the workspace), an asset id or an asset's file name. The CLI sends these as modifications. Add --video --format mp4 for the page's motion, --page <id or name> for another page, and --data file.json to pass modifications as the API takes them, including page keys such as k7fq2m8a@Headline.

A batch from a CSV

headline,Hero image,price
Blue shirt,blue-shirt.jpg,₹499
Red shirt,./photos/red.jpg,₹549

kalpana batches create --template t4hz8c1n --csv products.csv --run --wait --out ./out

Columns are field ids or layer names. Empty cells keep the template's own value. With --run the batch is published and starts rendering. Without it the batch stays a draft, to review in the Studio and run when it is right. Then:

kalpana batches wait 9a2e6f31-5c7d-4b08-8e1a-d4f2c6b0a937
kalpana batches download 9a2e6f31-5c7d-4b08-8e1a-d4f2c6b0a937 --out ./out

kalpana batches run <batchId> renders the pending jobs of a batch, publishing a draft as it starts.

Only renders spend credits: render, batches create --run and batches run.

In CI

Pipe the key in, or skip the config file and set the environment:

echo "$KALPANA_API_KEY" | kalpana login --with-key-stdin
KALPANA_API_KEY=sk-... kalpana templates list

Keep several accounts with --profile <name>.

Everything else

kalpana jobs get 7b0c2d1e-4f5a-4c8b-9e3d-2a6f1b8c0d11   # one job's status and file
kalpana jobs wait 7b0c2d1e-4f5a-4c8b-9e3d-2a6f1b8c0d11  # wait until it is done
kalpana batches rows 9a2e6f31-5c7d-4b08-8e1a-d4f2c6b0a937  # a batch's jobs
kalpana assets upload ./photos/*.jpg
kalpana files list
kalpana workspaces list

Every command takes --json for scripts and --help for its options. Progress goes to stderr, so --json output pipes cleanly into jq. List commands show one page; --limit or --all show more.

Exit code	Meaning
0	Done
1	The API or a render failed
2	The command was used wrongly
3	Not logged in, or the key was refused

Environment variables: KALPANA_API_KEY, KALPANA_WORKSPACE, KALPANA_BASE_URL, KALPANA_PROFILE, KALPANA_CONFIG_DIR, NO_COLOR.

The package is on npm as @kalpana-one/cli. It is built on the TypeScript SDK.