CLI reference

Install with curl -fsSL https://api.cloudtifact.com/install.sh | sh. Once it's on npm, npx cloudtifact works too. Every command takes --help.

Agents: add --toon (compact tables, fewest tokens) or --json to commands that print data, or set CLOUDTIFACT_FORMAT=toon.

cloudtifact login [options]

Option	Notes
`--no-browser`	don't open a browser, just print the URL (automatic over SSH)

`whoami`

Show the signed-in user, their workspaces (current one marked) and pending invites

cloudtifact whoami [options]

Option	Notes
`--toon`	print TOON (compact, for agents)
`--json`	print JSON

`logout`

Revoke the saved token on the server and forget it

cloudtifact logout [options]

`workspace`

Your workspaces: where spaces live, with members and roles

cloudtifact workspace [options] [command]

`workspace list`

List your workspaces; * marks the current one (where new spaces go)

cloudtifact workspace list [options]

Option	Notes
`--toon`	print TOON (compact, for agents)
`--json`	print JSON

`workspace use`

Make a workspace the default for new spaces (saved in the global config)

cloudtifact workspace use [options] <slug>

Argument	Required	Notes
`slug`	yes	workspace slug

`workspace create`

Create a workspace; you become its owner

cloudtifact workspace create [options] <slug>

Argument	Required	Notes
`slug`	yes	workspace slug, e.g. overjoy

Option	Notes
`--name <name>`	display name (default: the slug)

`workspace invite`

Invite someone by handle; they get access once they accept

cloudtifact workspace invite [options] <handle>

Argument	Required	Notes
`handle`	yes	their handle

Option	Notes
`--role <role>`	role (default `member`)
`--workspace <slug>`	workspace (default: the current one)

`workspace accept`

Accept your pending invite to a workspace

cloudtifact workspace accept [options] <slug>

Argument	Required	Notes
`slug`	yes	workspace slug

`workspace decline`

Decline your pending invite to a workspace

cloudtifact workspace decline [options] <slug>

Argument	Required	Notes
`slug`	yes	workspace slug

`init`

Link this repo to a space (creating one in the current workspace if needed) and write .cloudtifact.json

cloudtifact init [options]

Option	Notes
`--dir <dir>`	folder to publish, relative to the repo root
`--workspace <slug>`	workspace for a new space (default: the current one, see `workspace list`)
`--visibility <v>`	who can view a new space
`--space <id>`	link an existing space instead of creating one
`--name <name>`	name for a new space (default: the repo folder name)
`-y, --yes`	accept defaults, no prompts
`--hooks`	also install agent hooks (see `hooks install`)

`push`

Upload changed files and record a new version on every target

cloudtifact push [options]

Option	Notes
`-m, --message <message>`	version message
`--dry-run`	show what would change, upload nothing
`-q, --quiet`	print nothing unless something fails
`--no-db`	don't run the docs folder's db/*.sql files

`status`

Show local changes since the latest version on each target

cloudtifact status [options]

Option	Notes
`--toon`	print TOON (compact, for agents)
`--json`	print JSON

`watch`

Push on every change to the docs folder

cloudtifact watch [options]

Option	Notes
`-m, --message <message>`	version message for each push

`comments`

Print open comment threads as Markdown for an agent

cloudtifact comments [options]

Option	Notes
`--path <path>`	only comments on this doc (relative to the docs folder)
`--all`	include resolved threads
`--space <id>`	space id (default: the first target in .cloudtifact.json)
`--toon`	print TOON: one flat table of comments, the cheapest format for an agent
`--json`	print JSON (the API's thread objects)

`reply`

Reply to a comment thread

cloudtifact reply [options] <commentId> <text...>

Argument	Required	Notes
`commentId`	yes
`text...`	yes	reply text

Option	Notes
`--space <id>`	space id (default: search this repo's targets)

`edit`

Edit a comment or reply you wrote; the old text is kept in its history

cloudtifact edit [options] <commentId> [text...]

Argument	Required	Notes
`commentId`	yes
`text...`	no	new text (or use --file, or pipe it in with -)

Option	Notes
`--file <path>`	read the new text from a file

`history`

Show every version of a comment: who wrote it, and through which agent

cloudtifact history [options] <commentId>

Argument	Required	Notes
`commentId`	yes

Option	Notes
`--toon`	print TOON (compact, for agents)
`--json`	print JSON

`resolve`

Resolve a comment thread

cloudtifact resolve [options] <commentId>

Argument	Required	Notes
`commentId`	yes

`unresolve`

Reopen a comment thread

cloudtifact unresolve [options] <commentId>

Argument	Required	Notes
`commentId`	yes

`publish`

Publish an HTML page (with the files it references) or a folder; prints its link

cloudtifact publish [options] <path>

Argument	Required	Notes
`path`	yes	an .html file or a folder with index.html

Option	Notes
`--public`	anyone with the link can view (only when first published; default: private)
`--name <name>`	space name (default: the page's <title>, else the file name)
`--workspace <slug>`	workspace for a new space (default: the current one, see `workspace list`)
`--entry <file>`	folder only: the page to publish as index.html
`-m, --message <message>`	version message
`--no-db`	don't run the db/*.sql files next to the page

`artifacts`

List pages published with cloudtifact publish

cloudtifact artifacts [options]

Option	Notes
`--toon`	print TOON (compact, for agents)
`--json`	print JSON

`versions`

List a space's versions, newest first

cloudtifact versions [options]

Option	Notes
`--space <id>`	space id (default: the first target in .cloudtifact.json)
`-n, --limit <n>`	how many to show (default `20`)
`--toon`	print TOON (compact, for agents)
`--json`	print JSON

`db`

Query and manage a space's database (one SQLite database per space)

cloudtifact db [options] [command]

`db query`

Run SQL against the space's database; read-only unless --write

cloudtifact db query [options] [sql]

Argument	Required	Notes
`sql`	no	the SQL to run (or use -f)

Option	Notes
`-f, --file <path>`	read the SQL from a file (files over 100 KB are split by statement; needs --write)
`--param <value>`	bind the next ? placeholder (repeatable; sent as strings)
`--write`	allow writes and schema changes (needs push access)
`--space <id>`	space id (default: the first target in .cloudtifact.json)
`--toon`	print TOON (compact, for agents)
`--json`	print JSON (the API's { columns, rows, ... } as returned)

`db schema`

List tables with their columns and row counts, and the database size

cloudtifact db schema [options]

Option	Notes
`--space <id>`	space id (default: the first target in .cloudtifact.json)
`--toon`	print TOON (compact, for agents)
`--json`	print JSON

`db export`

Dump the database as SQL (replay it with db query --write -f)

cloudtifact db export [options]

Option	Notes
`-o, --output <file>`	write to this file instead of stdout
`--space <id>`	space id (default: the first target in .cloudtifact.json)

`db reset`

Delete every table and row (admins only; undo with db restore)

cloudtifact db reset [options]

Option	Notes
`-y, --yes`	don't ask for confirmation
`--space <id>`	space id (default: the first target in .cloudtifact.json)

`db restore`

Roll the database back to a point in time within the last 30 days (admins only)

cloudtifact db restore [options]

Option	Notes
`--at <time>`	ISO 8601 time, e.g. 2026-09-28T10:00:00Z (or Unix ms)
`-y, --yes`	don't ask for confirmation
`--space <id>`	space id (default: the first target in .cloudtifact.json)
`--toon`	print TOON (compact, for agents)
`--json`	print JSON

`db writes`

The write log, newest first: who wrote (member or guest), from where, and what

cloudtifact db writes [options]

Option	Notes
`-n, --limit <n>`	how many (default 100, max 500)
`--space <id>`	space id (default: the first target in .cloudtifact.json)
`--toon`	print TOON (compact, for agents)
`--json`	print JSON

`db guest-writes`

The named writes guests may run in this space (from the page folder's db/guest-writes.sql)

cloudtifact db guest-writes [options]

Option	Notes
`--space <id>`	space id (default: the first target in .cloudtifact.json)
`--toon`	print TOON (compact, for agents)
`--json`	print JSON

`db migrate`

Run the folder's db/*.sql files not yet applied, in filename order, without publishing

cloudtifact db migrate [options]

Option	Notes
`--space <id>`	space id (default: the first target in .cloudtifact.json)
`--dir <folder>`	folder holding db/ (default: the linked repo's docs folder, else the current one)
`--dry-run`	list the files that would run; change nothing

`hooks`

Agent hooks that push after each edit

cloudtifact hooks [options] [command]

`hooks install`

Merge a post-edit hook into each harness's project config (default: all detected)

cloudtifact hooks install [options]

Option	Notes
`--claude`	Claude Code: .claude/settings.json PostToolUse
`--codex`	Codex: .codex/hooks.json PostToolUse (apply_patch)
`--cursor`	Cursor: .cursor/hooks.json afterFileEdit

`skill`

The agent skill that teaches agents to use Cloudtifact

cloudtifact skill [options] [command]

`skill install`

Write cloudtifact/SKILL.md into every agent skills folder on this machine

cloudtifact skill install [options]

loginCopy Anchor Link

whoamiCopy Anchor Link

logoutCopy Anchor Link

workspaceCopy Anchor Link

workspace listCopy Anchor Link

workspace useCopy Anchor Link

workspace createCopy Anchor Link

workspace inviteCopy Anchor Link

workspace acceptCopy Anchor Link

workspace declineCopy Anchor Link

initCopy Anchor Link

pushCopy Anchor Link

statusCopy Anchor Link

watchCopy Anchor Link

commentsCopy Anchor Link

replyCopy Anchor Link

editCopy Anchor Link

historyCopy Anchor Link

resolveCopy Anchor Link

unresolveCopy Anchor Link

publishCopy Anchor Link

artifactsCopy Anchor Link

versionsCopy Anchor Link

dbCopy Anchor Link

db queryCopy Anchor Link

db schemaCopy Anchor Link

db exportCopy Anchor Link

db resetCopy Anchor Link

db restoreCopy Anchor Link

db writesCopy Anchor Link

db guest-writesCopy Anchor Link

db migrateCopy Anchor Link

hooksCopy Anchor Link

hooks installCopy Anchor Link

skillCopy Anchor Link

skill installCopy Anchor Link

On this page

`login`