CLI reference
Every cloudy command and option (cloudy 0.3.3).
Install with npm i -g usecloudy, then type cloudy (cloudtifact still works as the same command). npx usecloudy runs it without installing. Every command takes --help.
Agents: add --toon (compact tables, fewest tokens) or --json to commands that print data, or set CLOUDTIFACT_FORMAT=toon.
login
Sign in through your browser (GitHub, Google or email) and save a token to the global config
cloudy 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
cloudy whoami [options]| Option | Notes |
|---|---|
--toon | print TOON (compact, for agents) |
--json | print JSON |
logout
Sign out of the active account (or --account <handle>, or --all): revoke its token and forget it
cloudy logout [options]| Option | Notes |
|---|---|
--all | sign out of every account on this machine |
accounts
List the accounts signed in on this machine (* = active)
cloudy accounts [options]| Option | Notes |
|---|---|
--toon | print TOON (compact, for agents) |
--json | print JSON |
switch
Make another signed-in account the active one; with --here, use it in this folder only
cloudy switch [options] [handle]| Argument | Required | Notes |
|---|---|---|
handle | no | the account to use (with two accounts, switch with no handle toggles) |
| Option | Notes |
|---|---|
--here | use this account in this folder (the repo root) and below, on this machine only |
--unbind | stop this folder using a set account |
workspace
Your workspaces: where spaces live, with members and roles
cloudy workspace [options] [command]workspace list
List your workspaces; * marks the current one (where new spaces go)
cloudy 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)
cloudy workspace use [options] <slug>| Argument | Required | Notes |
|---|---|---|
slug | yes | workspace slug |
workspace create
Create a workspace; you become its owner
cloudy 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
cloudy 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
cloudy workspace accept [options] <slug>| Argument | Required | Notes |
|---|---|---|
slug | yes | workspace slug |
workspace decline
Decline your pending invite to a workspace
cloudy 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
cloudy 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 (default: private) |
--space <id> | link an existing space (id or link) 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
cloudy 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 |
--strict | make a page the space can't back an error, so nothing is pushed |
--project <name> | the project this work belongs to (default: the git repo's name) |
status
Show local changes since the latest version on each target
cloudy status [options]| Option | Notes |
|---|---|
--toon | print TOON (compact, for agents) |
--json | print JSON |
watch
Push on every change to the docs folder
cloudy watch [options]| Option | Notes |
|---|---|
-m, --message <message> | version message for each push |
comments
Print open comment threads as Markdown for an agent
cloudy comments [options]| Option | Notes |
|---|---|
--path <path> | only comments on this doc (relative to the docs folder) |
--all | include resolved threads |
--space <id> | space id, public link, or copied URL (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) |
comment
Start a comment thread on a page (agents: comments show as "via <your agent>")
cloudy comment [options] [text...]| Argument | Required | Notes |
|---|---|---|
text... | no | comment text (or use --file, or pipe it in with -) |
| Option | Notes |
|---|---|
--space <id> | space id, public link, or copied URL (default: the first target in .cloudtifact.json) |
--path <path> | the page to comment on (default: the space's only page, or its index) |
--quote <text> | the exact words on the page the comment is about |
--file <path> | read the comment from a file |
context
Print the Discord thread linked to this space as Markdown for an agent: what the team said about it
cloudy context [options] [command]| Option | Notes |
|---|---|
--all | every message (default: the newest 500 of a thread, or 200 of a channel) |
--space <id> | space id, public link, or copied URL (default: the first target in .cloudtifact.json) |
--json | print JSON (the API's chat objects) |
context pull
Fetch the Discord messages linked to this space (same as cloudy context)
cloudy context pull [options]| Option | Notes |
|---|---|
--all | every message (default: the newest 500 of a thread, or 200 of a channel) |
--space <id> | space id, public link, or copied URL (default: the first target in .cloudtifact.json) |
--json | print JSON (the API's chat objects) |
reply
Reply to a comment thread
cloudy reply [options] <commentId> [text...]| Argument | Required | Notes |
|---|---|---|
commentId | yes | |
text... | no | reply text (or use --file, or pipe it in with -) |
| Option | Notes |
|---|---|
--space <id> | space id, public link, or copied URL (default: search this repo's targets) |
--file <path> | read the reply from a file |
edit
Edit a comment or reply you wrote; the old text is kept in its history
cloudy 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
cloudy history [options] <commentId>| Argument | Required | Notes |
|---|---|---|
commentId | yes |
| Option | Notes |
|---|---|
--toon | print TOON (compact, for agents) |
--json | print JSON |
resolve
Resolve a comment thread
cloudy resolve [options] <commentId>| Argument | Required | Notes |
|---|---|---|
commentId | yes |
unresolve
Reopen a comment thread
cloudy unresolve [options] <commentId>| Argument | Required | Notes |
|---|---|---|
commentId | yes |
publish
Publish an HTML page (with the files it references) or a folder; prints its link
cloudy 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). Agents: only when the user asks |
--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) |
--space <id> | publish as this existing space's main page (id or link), replacing its files |
--keep-pages | with --space: replace only the files you publish (its home page, say) and keep the space's other pages and files |
--add-to <id> | add it as a page in this existing space (id or link), keeping the space's other pages |
--new | make a new space, even when an existing one looks like the same topic |
--folder <path> | file a new space in this folder, like "Deals/Enterprise" (see cloudy folders) |
--project <name> | the project this work belongs to (default: the git repo it's in) |
--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 |
--strict | make a page the space can't back an error, so nothing is published |
copy
Make your own copy of a Cloudy page someone sent you: a new space in your workspace
cloudy copy [options] <url>| Argument | Required | Notes |
|---|---|---|
url | yes | a Cloudy page link, space id, or public link |
| Option | Notes |
|---|---|
--at <n> | the version to copy (default: the one in the URL, else latest) |
--name <name> | name for the new space (default: the original's name) |
--workspace <slug> | workspace for the new space (default: the current one, see workspace list) |
--public | anyone with the link can view (default: private). Agents: only when the user asks |
-o, --output <dir> | also write the files into this folder |
--force | overwrite files in -o |
--no-publish | write files with -o and don't make a new space |
-m, --message <message> | version message on the new space |
--strict | make a page the space can't back an error, so nothing is published |
--toon | print TOON (compact, for agents) |
--json | print JSON |
find
Find the spaces a topic already lives in, best match first, so new work can go in as a page
cloudy find [options] <words...>| Argument | Required | Notes |
|---|---|---|
words... | yes | what it's about, like a title |
| Option | Notes |
|---|---|
--workspace <slug> | only this workspace (default: all of yours) |
--toon | print TOON (compact, for agents) |
--json | print JSON |
artifacts
List pages published with cloudy publish
cloudy artifacts [options]| Option | Notes |
|---|---|
--toon | print TOON (compact, for agents) |
--json | print JSON |
versions
List a space's versions, newest first
cloudy versions [options]| Option | Notes |
|---|---|
--space <id> | space id, public link, or copied URL (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 |
settings
Show who can open a space and its guest and visitor switches, or change them (space admins; the same switches as in the app)
cloudy settings [options]| Option | Notes |
|---|---|
--space <id> | space id, public link, or copied URL (default: the first target in .cloudtifact.json) |
--visibility <private|public> | who can open it: private (only members of its workspace; members also works) or public (anyone with the link). Going public turns guest comments on; going private turns guest comments, guest writes and search engines off |
--guest-writes <on|off> | Pages can save data for people who are not signed in |
--pages-show-data <on|off> | Pages can show saved data (off keeps the database private from visitors) |
--guest-comments <on|off> | People who are not signed in can comment |
--search <on|off> | Show its pages in search engines (public spaces with no password; off by default, and other public pages stay out of search) |
--link <name> | set the public link (lowercase letters, numbers and single dashes; off clears it, and an old link goes to the new one) |
--toon | print TOON (compact, for agents) |
--json | print JSON |
archive
Archive a space: it leaves every list, its link, comments and data keep working, and a new version brings it back
cloudy archive [options] [space]| Argument | Required | Notes |
|---|---|---|
space | no | space id, public link, or copied URL (default: the first target in .cloudtifact.json) |
| Option | Notes |
|---|---|
--space <id> | space id, public link, or copied URL (same as the argument) |
--json | print JSON |
unarchive
Bring an archived space back into the lists
cloudy unarchive [options] [space]| Argument | Required | Notes |
|---|---|---|
space | no | space id, public link, or copied URL (default: the first target in .cloudtifact.json) |
| Option | Notes |
|---|---|
--space <id> | space id, public link, or copied URL (same as the argument) |
--json | print JSON |
spaces
List spaces: the ones you made, the ones shared with you, or the ones waiting on you
cloudy spaces [options]| Option | Notes |
|---|---|
--mine | only the ones you made (Made by me) |
--shared | only the ones people in other workspaces shared with you (Shared with me) |
--waiting | comment threads waiting on you, by space (Waiting on me) |
--workspace <slug> | which workspace (default: your default one) |
--folder <path> | only the spaces in this folder ("/" for the ones in no folder) |
--toon | print TOON (compact, for agents) |
--json | print JSON |
activity
What people did to the spaces of a workspace, newest first, with the id to undo each
cloudy activity [options]| Option | Notes |
|---|---|
--workspace <slug> | which workspace (default: your default one) |
--person <handle> | only what this person did |
-n, --limit <n> | how many to show (default 20) |
--toon | print TOON (compact, for agents) |
--json | print JSON |
undo
Undo a change from cloudy activity: brings back, restores, or takes out an added page
cloudy undo [options] <id>| Argument | Required | Notes |
|---|---|---|
id | yes | the change's id, from cloudy activity |
| Option | Notes |
|---|---|
--workspace <slug> | which workspace (default: your default one) |
folders
The workspace's folders: every path, how many spaces, and what each is for (read it before filing)
cloudy folders [options]| Option | Notes |
|---|---|
--workspace <slug> | which workspace (default: your default one) |
--toon | print TOON (compact, for agents) |
--json | print JSON |
folder
Make, rename, describe or move folders (each change is in Activity, with Undo)
cloudy folder [options] [command]folder create
Make a folder; a path like "Deals/Enterprise" makes the folders it needs
cloudy folder create [options] <path>| Argument | Required | Notes |
|---|---|---|
path | yes | the folder's path |
| Option | Notes |
|---|---|
--description <text> | what goes in it (people and agents read this before filing) |
--workspace <slug> | which workspace (default: your default one) |
folder rename
Rename a folder
cloudy folder rename [options] <path> <name>| Argument | Required | Notes |
|---|---|---|
path | yes | the folder's path or id |
name | yes | its new name |
| Option | Notes |
|---|---|
--workspace <slug> | which workspace (default: your default one) |
folder describe
Say what goes in a folder (people and agents read it before filing); empty text clears it
cloudy folder describe [options] <path> <text>| Argument | Required | Notes |
|---|---|---|
path | yes | the folder's path or id |
text | yes | one line |
| Option | Notes |
|---|---|
--workspace <slug> | which workspace (default: your default one) |
folder move
Move a folder (and everything in it) into another one, or to the top level with "/"
cloudy folder move [options] <path> <to>| Argument | Required | Notes |
|---|---|---|
path | yes | the folder's path or id |
to | yes | where: a folder path, or "/" for the top level |
| Option | Notes |
|---|---|
--workspace <slug> | which workspace (default: your default one) |
move
Move a space into a folder, or to the top level with "/"; its link and who can open it stay the same
cloudy move [options] <space> <folder>| Argument | Required | Notes |
|---|---|---|
space | yes | space id, public link, or copied URL |
folder | yes | a folder path like "Product plans/Pricing", or "/" |
favorite
Add a space to your favorites, at the top of your sidebar (only you see them)
cloudy favorite [options] [space]| Argument | Required | Notes |
|---|---|---|
space | no | space id, public link, or copied URL (default: the first target in .cloudtifact.json) |
| Option | Notes |
|---|---|
--space <id> | space id, public link, or copied URL (same as the argument) |
--remove | take it off your favorites |
upload
Upload files of any type into a space (up to 100 MB each); download them anywhere you sign in
cloudy upload [options] <files...>| Argument | Required | Notes |
|---|---|---|
files... | yes |
| Option | Notes |
|---|---|
--space <id> | space id, public link, or copied URL (default: the first target in .cloudtifact.json) |
uploads
List the files uploaded to a space, newest first
cloudy uploads [options]| Option | Notes |
|---|---|
--space <id> | space id, public link, or copied URL (default: the first target in .cloudtifact.json) |
--toon | print TOON (compact, for agents) |
--json | print JSON |
sources
List a space's "Files the AI reads" (chats, emails, PDFs, images...); get one with download --source
cloudy sources [options]| Option | Notes |
|---|---|
--space <id> | space id, public link, or copied URL (default: the first target in .cloudtifact.json) |
--toon | print TOON (compact, for agents) |
--json | print JSON |
capabilities
What a page can do (database, guest writes, ...): when to use each, how, and its docs page
cloudy capabilities [options]| Option | Notes |
|---|---|
--space <id> | space id, public link, or copied URL: also say which are on in that space |
--toon | print TOON (compact, for agents) |
--json | print JSON |
download
Download an uploaded file (by name or id), a pushed file with --file, or a space file with --source
cloudy download [options] [name]| Argument | Required | Notes |
|---|---|---|
name | no | the upload's name or id |
| Option | Notes |
|---|---|
--file <path> | download a pushed file instead (path in the space) |
--source <name> | download one of the space's "Files the AI reads" instead (name or id; see sources) |
--at <n> | with --file: the version to download from (default: latest) |
-o, --output <path> | where to save it (default: the file's name, in the current folder) |
--force | overwrite an existing file |
--space <id> | space id, public link, or copied URL (default: the first target in .cloudtifact.json) |
db
Query and manage a space's database (one SQLite database per space)
cloudy db [options] [command]db query
Run SQL against the space's database; read-only unless --write
cloudy 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, public link, or copied URL (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
cloudy db schema [options]| Option | Notes |
|---|---|
--space <id> | space id, public link, or copied URL (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)
cloudy db export [options]| Option | Notes |
|---|---|
-o, --output <file> | write to this file instead of stdout |
--space <id> | space id, public link, or copied URL (default: the first target in .cloudtifact.json) |
db reset
Delete every table and row (admins only; undo with db restore)
cloudy db reset [options]| Option | Notes |
|---|---|
-y, --yes | don't ask for confirmation |
--space <id> | space id, public link, or copied URL (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)
cloudy 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, public link, or copied URL (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
cloudy db writes [options]| Option | Notes |
|---|---|
-n, --limit <n> | how many (default 100, max 500) |
--space <id> | space id, public link, or copied URL (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)
cloudy db guest-writes [options]| Option | Notes |
|---|---|
--space <id> | space id, public link, or copied URL (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
cloudy db migrate [options]| Option | Notes |
|---|---|
--space <id> | space id, public link, or copied URL (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
cloudy hooks [options] [command]hooks install
Merge a post-edit hook into each harness's project config (default: all detected)
cloudy 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 |
hooks uninstall
Remove hooks this CLI added (only the agent rules ones for now; your push-after-edit hook stays)
cloudy hooks uninstall [options]| Option | Notes |
|---|---|
--rules | remove the agent rules hooks (session start, each request, session end) |
skill
The agent skill that teaches agents to use Cloudy
cloudy skill [options] [command]skill install
Write cloudtifact/SKILL.md into every agent skills folder, refreshing copies another CLI version wrote
cloudy skill install [options]| Option | Notes |
|---|---|
--check | only list the copies that are out of date; write nothing (exits 1 when any are) |
skill status
List the installed skill copies and the CLI version each was written with (exits 1 when any is out of date)
cloudy skill status [options]| Option | Notes |
|---|---|
--toon | print TOON (compact, for agents) |
--json | print JSON |
upgrade
Update the CLI to the latest version (when it was installed with the install script)
cloudy upgrade [options]| Option | Notes |
|---|---|
--undo | go back to the CLI the last upgrade replaced (run again to switch back) |