Project commands

Your library: list, pull, push, rename, archive, checkpoints, covers and links.

Preview

Every command names your library with --base-url and expects a signed-in machine. Writes name the revision they expect. Read Portable projects for pull and push.

puni projectYour library: list, pull, push, rename, archive, checkpoints, covers and links.

Command	What it does
`puni project list`	List your active scenes, newest first, a page at a time; --archived lists the archived ones instead.
`puni project get`	Read a scene's document, revision and cover, with server asset references.
`puni project create`	Create a scene in your library from a document or a portable file.
`puni project push`	Replace a scene's document, naming the revision you expect. Refused if the library moved on.
`puni project apply`	Land one batch of commands on the saved revision you last read, in one transaction. The scene keeps a checkpoint of what was there before, named by the label; a moved revision is refused.
`puni project update`	Change the saved scene's environment, description or both, on the revision you last read. It lands like apply: one new revision, with a checkpoint of what was there before named by the label.
`puni project pull`	Download a scene and its assets as one validated portable file.
`puni project rename`	Rename a scene.
`puni project archive`	Put a scene away and suspend its links.
`puni project restore`	Bring an archived scene back, with the links that were not revoked.
`puni project checkpoints`	List a scene's saved checkpoints.
`puni project checkpoint`	Keep a named checkpoint of the current document.
`puni project restore-checkpoint`	Make a checkpoint the current document, as a new revision.
`puni project cover-get`	Read a scene's cover metadata, or download the PNG.
`puni project cover-set`	Upload a PNG as the cover for a saved document.
`puni project shares`	List a scene's live links.
`puni project share`	Make an unlisted link to one saved revision, with its iframe snippet.
`puni project unshare`	Revoke a link.

#`project list`

List your active scenes, newest first, a page at a time. Add --archived to list the archived ones instead.

puni project list [--archived] --base-url https://puni.design

Flag	Type	Default	What it does
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--archived`	`boolean`	`false`	List the archived scenes instead of the active ones.
`--cursor`	`string`		Continue from a previous page.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `project list`

puni project list --base-url https://puni.design --json

#`project get`

Read a scene's document, revision and cover, with server asset references.

puni project get PROJECT_ID --base-url https://puni.design

Flag	Type	Default	What it does
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `project get`

puni project get quiet-guest --base-url https://puni.design --json

#`project create`

Create a scene in your library from a document or a portable file.

puni project create --file scene.json --base-url https://puni.design

Flag	Type	Default	What it does
`--file` required	`string`		The document or portable file to upload.
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `project create`

puni project create --file scene.puni.json --base-url https://puni.design --json

#`project push`

Replace a scene's document, naming the revision you expect. Refused if the library moved on.

puni project push PROJECT_ID --file scene.json --revision 4 --base-url https://puni.design

Flag	Type	Default	What it does
`--file` required	`string`		The document or portable file to upload.
`--revision` required	`number`		The revision you last read.
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `project push`

puni project push quiet-guest --file scene.puni.json --revision 8 --base-url https://puni.design --json

#`project apply`

Land one batch of commands on the saved revision you last read, in one transaction. The scene keeps a checkpoint of what was there before, named by the label, and the owner sees the new revision land. A moved revision is refused: pull, then send the batch again from the revision you read.

puni project apply PROJECT_ID --commands edits.json --revision 4 [--label text] --base-url https://puni.design

Flag	Type	Default	What it does
`--commands` required	`json`		A JSON array of composition commands.
`--revision` required	`number`		The revision you last read.
`--label`	`string`	`CLI edit`	What this edit changed, in the owner's words.
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `project apply`

puni project apply quiet-guest --commands edits.json --revision 8 --label 'Longer hold' --base-url https://puni.design --json

#`project update`

Change the saved scene's stage (lighting, exposure, shadows, background, transparency), its description, or both, on the revision you last read. It lands like project apply: one new revision, with a checkpoint of what was there before named by the label. Values are checked before anything is sent.

puni project update PROJECT_ID --revision 4 [--patch environment.json] [--brief text] [--label text] --base-url https://puni.design

Flag	Type	Default	What it does
`--revision` required	`number`		The revision you last read.
`--patch`	`json`		Environment fields to change: lighting soft, gallery or dark; exposure 0.1 to 3; shadows; background #rrggbb; transparent.
`--brief`	`string`		The scene's description, up to 300 characters.
`--label`	`string`	`CLI settings`	What this change does, in the owner's words.
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `project update`

puni project update quiet-guest --patch stage.json --brief 'Lockup on black' --revision 9 --base-url https://puni.design --json

#`project pull`

Download a scene and its assets as one validated portable file.

A scene larger than one API answer (4 MB) is read from the download address its metadata names, straight from storage and without your token. It is written only when its SHA-256 matches the saved scene; a mismatch reports PUNI_CHECKSUM and leaves the output alone. project get and project restore-checkpoint read large scenes and checkpoints the same way.

puni project pull PROJECT_ID --output scene.json [--asset-origin https://storage.example.com] --base-url https://puni.design

Flag	Type	Default	What it does
`--output` required	`string`		Where to write the portable file.
`--asset-origin`	`string`		The exact storage origin asset downloads may redirect to. An allowlist, not another API.
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--overwrite`	`boolean`	`false`	Replace the output file if it already exists.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `project pull`

puni project pull quiet-guest --output scene.puni.json --asset-origin https://storage.example.com --base-url https://puni.design --json

#`project rename`

Rename a scene.

puni project rename PROJECT_ID --name text --revision N --base-url https://puni.design

Flag	Type	Default	What it does
`--name` required	`string`		The new name.
`--revision` required	`number`		The revision you expect.
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `project rename`

puni project rename quiet-guest --name 'Quiet guest' --revision 8 --base-url https://puni.design --json

#`project archive`

Put a scene away and suspend its links.

puni project archive PROJECT_ID --revision N --base-url https://puni.design

Flag	Type	Default	What it does
`--revision` required	`number`		The revision you expect.
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `project archive`

puni project archive quiet-guest --revision 9 --base-url https://puni.design --json

#`project restore`

Bring an archived scene back, with the links that were not revoked.

puni project restore PROJECT_ID --revision N --base-url https://puni.design

Flag	Type	Default	What it does
`--revision` required	`number`		The revision you expect.
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `project restore`

puni project restore quiet-guest --revision 9 --base-url https://puni.design --json

#`project checkpoints`

List a scene's saved checkpoints.

puni project checkpoints PROJECT_ID --base-url https://puni.design

Flag	Type	Default	What it does
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--cursor`	`string`		Continue from a previous page.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `project checkpoints`

puni project checkpoints quiet-guest --base-url https://puni.design --json

#`project checkpoint`

Keep a named checkpoint of the current document.

puni project checkpoint PROJECT_ID --name text --revision N --base-url https://puni.design

Flag	Type	Default	What it does
`--name` required	`string`		The checkpoint's name.
`--revision` required	`number`		The revision you expect.
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `project checkpoint`

puni project checkpoint quiet-guest --name 'Before revision' --revision 8 --base-url https://puni.design --json

#`project restore-checkpoint`

Make a checkpoint the current document, as a new revision.

puni project restore-checkpoint PROJECT_ID --checkpoint ID --revision N --base-url https://puni.design

Flag	Type	Default	What it does
`--checkpoint` required	`string`		The checkpoint to restore.
`--revision` required	`number`		The revision you expect.
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `project restore-checkpoint`

puni project restore-checkpoint quiet-guest --checkpoint chk_8 --revision 9 --base-url https://puni.design --json

#`project cover-get`

Read a scene's cover metadata, or download the PNG.

puni project cover-get PROJECT_ID [--output cover.png] --base-url https://puni.design

Flag	Type	Default	What it does
`--output`	`string`		Download the cover here.
`--asset-origin`	`string`		The exact storage origin asset downloads may redirect to. An allowlist, not another API.
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--overwrite`	`boolean`	`false`	Replace the output file if it already exists.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `project cover-get`

puni project cover-get quiet-guest --base-url https://puni.design --json

#`project cover-set`

Upload a PNG as the cover for a saved document.

puni project cover-set PROJECT_ID --file cover.png --document-hash SHA256 --base-url https://puni.design

Flag	Type	Default	What it does
`--file` required	`string`		A PNG of at most 2 MB and 1024 pixels on a side.
`--document-hash` required	`string`		The saved document's SHA-256 the cover depicts.
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `project cover-set`

puni project cover-set quiet-guest --file cover.png --document-hash 5b7d… --base-url https://puni.design --json

#`project shares`

List a scene's live links.

puni project shares PROJECT_ID --base-url https://puni.design

Flag	Type	Default	What it does
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `project shares`

puni project shares quiet-guest --base-url https://puni.design --json

Make an unlisted link to one saved revision, with its iframe snippet.

puni project share PROJECT_ID --revision N --base-url https://puni.design

Flag	Type	Default	What it does
`--revision` required	`number`		The revision to share.
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

puni project share quiet-guest --revision 8 --base-url https://puni.design --json

#`project unshare`

Revoke a link.

puni project unshare PROJECT_ID --share LINK_ID --base-url https://puni.design

Flag	Type	Default	What it does
`--share` required	`string`		The link to revoke.
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `project unshare`

puni project unshare quiet-guest --share lnk_… --base-url https://puni.design --json

Back to the command line index for every group.

Was this useful?

#project list

#Run project list

#project get

#Run project get

#project create

#Run project create

#project push

#Run project push

#project apply

#Run project apply

#project update

#Run project update

#project pull

#Run project pull

#project rename

#Run project rename

#project archive

#Run project archive

#project restore

#Run project restore

#project checkpoints

#Run project checkpoints

#project checkpoint

#Run project checkpoint

#project restore-checkpoint

#Run project restore-checkpoint

#project cover-get

#Run project cover-get

#project cover-set

#Run project cover-set

#project shares

#Run project shares

#project share

#Run project share

#project unshare

#Run project unshare