Skip to content
Cloudy docs

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]
OptionNotes
--no-browserdon'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]
OptionNotes
--toonprint TOON (compact, for agents)
--jsonprint JSON

logout

Sign out of the active account (or --account <handle>, or --all): revoke its token and forget it

cloudy logout [options]
OptionNotes
--allsign out of every account on this machine

accounts

List the accounts signed in on this machine (* = active)

cloudy accounts [options]
OptionNotes
--toonprint TOON (compact, for agents)
--jsonprint JSON

switch

Make another signed-in account the active one; with --here, use it in this folder only

cloudy switch [options] [handle]
ArgumentRequiredNotes
handlenothe account to use (with two accounts, switch with no handle toggles)
OptionNotes
--hereuse this account in this folder (the repo root) and below, on this machine only
--unbindstop 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]
OptionNotes
--toonprint TOON (compact, for agents)
--jsonprint JSON

workspace use

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

cloudy workspace use [options] <slug>
ArgumentRequiredNotes
slugyesworkspace slug

workspace create

Create a workspace; you become its owner

cloudy workspace create [options] <slug>
ArgumentRequiredNotes
slugyesworkspace slug, e.g. overjoy
OptionNotes
--name &lt;name&gt;display name (default: the slug)

workspace invite

Invite someone by handle; they get access once they accept

cloudy workspace invite [options] <handle>
ArgumentRequiredNotes
handleyestheir handle
OptionNotes
--role &lt;role&gt;role (default member)
--workspace &lt;slug&gt;workspace (default: the current one)

workspace accept

Accept your pending invite to a workspace

cloudy workspace accept [options] <slug>
ArgumentRequiredNotes
slugyesworkspace slug

workspace decline

Decline your pending invite to a workspace

cloudy workspace decline [options] <slug>
ArgumentRequiredNotes
slugyesworkspace slug

init

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

cloudy init [options]
OptionNotes
--dir &lt;dir&gt;folder to publish, relative to the repo root
--workspace &lt;slug&gt;workspace for a new space (default: the current one, see workspace list)
--visibility &lt;v&gt;who can view a new space (default: private)
--space &lt;id&gt;link an existing space (id or link) instead of creating one
--name &lt;name&gt;name for a new space (default: the repo folder name)
-y, --yesaccept defaults, no prompts
--hooksalso install agent hooks (see hooks install)

push

Upload changed files and record a new version on every target

cloudy push [options]
OptionNotes
-m, --message &lt;message&gt;version message
--dry-runshow what would change, upload nothing
-q, --quietprint nothing unless something fails
--no-dbdon't run the docs folder's db/*.sql files
--strictmake a page the space can't back an error, so nothing is pushed
--project &lt;name&gt;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]
OptionNotes
--toonprint TOON (compact, for agents)
--jsonprint JSON

watch

Push on every change to the docs folder

cloudy watch [options]
OptionNotes
-m, --message &lt;message&gt;version message for each push

comments

Print open comment threads as Markdown for an agent

cloudy comments [options]
OptionNotes
--path &lt;path&gt;only comments on this doc (relative to the docs folder)
--allinclude resolved threads
--space &lt;id&gt;space id, public link, or copied URL (default: the first target in .cloudtifact.json)
--toonprint TOON: one flat table of comments, the cheapest format for an agent
--jsonprint 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...]
ArgumentRequiredNotes
text...nocomment text (or use --file, or pipe it in with -)
OptionNotes
--space &lt;id&gt;space id, public link, or copied URL (default: the first target in .cloudtifact.json)
--path &lt;path&gt;the page to comment on (default: the space's only page, or its index)
--quote &lt;text&gt;the exact words on the page the comment is about
--file &lt;path&gt;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]
OptionNotes
--allevery message (default: the newest 500 of a thread, or 200 of a channel)
--space &lt;id&gt;space id, public link, or copied URL (default: the first target in .cloudtifact.json)
--jsonprint JSON (the API's chat objects)

context pull

Fetch the Discord messages linked to this space (same as cloudy context)

cloudy context pull [options]
OptionNotes
--allevery message (default: the newest 500 of a thread, or 200 of a channel)
--space &lt;id&gt;space id, public link, or copied URL (default: the first target in .cloudtifact.json)
--jsonprint JSON (the API's chat objects)

reply

Reply to a comment thread

cloudy reply [options] <commentId> [text...]
ArgumentRequiredNotes
commentIdyes
text...noreply text (or use --file, or pipe it in with -)
OptionNotes
--space &lt;id&gt;space id, public link, or copied URL (default: search this repo's targets)
--file &lt;path&gt;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...]
ArgumentRequiredNotes
commentIdyes
text...nonew text (or use --file, or pipe it in with -)
OptionNotes
--file &lt;path&gt;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>
ArgumentRequiredNotes
commentIdyes
OptionNotes
--toonprint TOON (compact, for agents)
--jsonprint JSON

resolve

Resolve a comment thread

cloudy resolve [options] <commentId>
ArgumentRequiredNotes
commentIdyes

unresolve

Reopen a comment thread

cloudy unresolve [options] <commentId>
ArgumentRequiredNotes
commentIdyes

publish

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

cloudy publish [options] <path>
ArgumentRequiredNotes
pathyesan .html file or a folder with index.html
OptionNotes
--publicanyone with the link can view (only when first published; default: private). Agents: only when the user asks
--name &lt;name&gt;space name (default: the page's <title>, else the file name)
--workspace &lt;slug&gt;workspace for a new space (default: the current one, see workspace list)
--space &lt;id&gt;publish as this existing space's main page (id or link), replacing its files
--keep-pageswith --space: replace only the files you publish (its home page, say) and keep the space's other pages and files
--add-to &lt;id&gt;add it as a page in this existing space (id or link), keeping the space's other pages
--newmake a new space, even when an existing one looks like the same topic
--folder &lt;path&gt;file a new space in this folder, like "Deals/Enterprise" (see cloudy folders)
--project &lt;name&gt;the project this work belongs to (default: the git repo it's in)
--entry &lt;file&gt;folder only: the page to publish as index.html
-m, --message &lt;message&gt;version message
--no-dbdon't run the db/*.sql files next to the page
--strictmake 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>
ArgumentRequiredNotes
urlyesa Cloudy page link, space id, or public link
OptionNotes
--at &lt;n&gt;the version to copy (default: the one in the URL, else latest)
--name &lt;name&gt;name for the new space (default: the original's name)
--workspace &lt;slug&gt;workspace for the new space (default: the current one, see workspace list)
--publicanyone with the link can view (default: private). Agents: only when the user asks
-o, --output &lt;dir&gt;also write the files into this folder
--forceoverwrite files in -o
--no-publishwrite files with -o and don't make a new space
-m, --message &lt;message&gt;version message on the new space
--strictmake a page the space can't back an error, so nothing is published
--toonprint TOON (compact, for agents)
--jsonprint 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...>
ArgumentRequiredNotes
words...yeswhat it's about, like a title
OptionNotes
--workspace &lt;slug&gt;only this workspace (default: all of yours)
--toonprint TOON (compact, for agents)
--jsonprint JSON

artifacts

List pages published with cloudy publish

cloudy artifacts [options]
OptionNotes
--toonprint TOON (compact, for agents)
--jsonprint JSON

versions

List a space's versions, newest first

cloudy versions [options]
OptionNotes
--space &lt;id&gt;space id, public link, or copied URL (default: the first target in .cloudtifact.json)
-n, --limit &lt;n&gt;how many to show (default 20)
--toonprint TOON (compact, for agents)
--jsonprint 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]
OptionNotes
--space &lt;id&gt;space id, public link, or copied URL (default: the first target in .cloudtifact.json)
--visibility &lt;private|public&gt;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 &lt;on|off&gt;Pages can save data for people who are not signed in
--pages-show-data &lt;on|off&gt;Pages can show saved data (off keeps the database private from visitors)
--guest-comments &lt;on|off&gt;People who are not signed in can comment
--search &lt;on|off&gt;Show its pages in search engines (public spaces with no password; off by default, and other public pages stay out of search)
--link &lt;name&gt;set the public link (lowercase letters, numbers and single dashes; off clears it, and an old link goes to the new one)
--toonprint TOON (compact, for agents)
--jsonprint 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]
ArgumentRequiredNotes
spacenospace id, public link, or copied URL (default: the first target in .cloudtifact.json)
OptionNotes
--space &lt;id&gt;space id, public link, or copied URL (same as the argument)
--jsonprint JSON

unarchive

Bring an archived space back into the lists

cloudy unarchive [options] [space]
ArgumentRequiredNotes
spacenospace id, public link, or copied URL (default: the first target in .cloudtifact.json)
OptionNotes
--space &lt;id&gt;space id, public link, or copied URL (same as the argument)
--jsonprint JSON

spaces

List spaces: the ones you made, the ones shared with you, or the ones waiting on you

cloudy spaces [options]
OptionNotes
--mineonly the ones you made (Made by me)
--sharedonly the ones people in other workspaces shared with you (Shared with me)
--waitingcomment threads waiting on you, by space (Waiting on me)
--workspace &lt;slug&gt;which workspace (default: your default one)
--folder &lt;path&gt;only the spaces in this folder ("/" for the ones in no folder)
--toonprint TOON (compact, for agents)
--jsonprint JSON

activity

What people did to the spaces of a workspace, newest first, with the id to undo each

cloudy activity [options]
OptionNotes
--workspace &lt;slug&gt;which workspace (default: your default one)
--person &lt;handle&gt;only what this person did
-n, --limit &lt;n&gt;how many to show (default 20)
--toonprint TOON (compact, for agents)
--jsonprint JSON

undo

Undo a change from cloudy activity: brings back, restores, or takes out an added page

cloudy undo [options] <id>
ArgumentRequiredNotes
idyesthe change's id, from cloudy activity
OptionNotes
--workspace &lt;slug&gt;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]
OptionNotes
--workspace &lt;slug&gt;which workspace (default: your default one)
--toonprint TOON (compact, for agents)
--jsonprint 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>
ArgumentRequiredNotes
pathyesthe folder's path
OptionNotes
--description &lt;text&gt;what goes in it (people and agents read this before filing)
--workspace &lt;slug&gt;which workspace (default: your default one)

folder rename

Rename a folder

cloudy folder rename [options] <path> <name>
ArgumentRequiredNotes
pathyesthe folder's path or id
nameyesits new name
OptionNotes
--workspace &lt;slug&gt;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>
ArgumentRequiredNotes
pathyesthe folder's path or id
textyesone line
OptionNotes
--workspace &lt;slug&gt;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>
ArgumentRequiredNotes
pathyesthe folder's path or id
toyeswhere: a folder path, or "/" for the top level
OptionNotes
--workspace &lt;slug&gt;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>
ArgumentRequiredNotes
spaceyesspace id, public link, or copied URL
folderyesa 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]
ArgumentRequiredNotes
spacenospace id, public link, or copied URL (default: the first target in .cloudtifact.json)
OptionNotes
--space &lt;id&gt;space id, public link, or copied URL (same as the argument)
--removetake 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...>
ArgumentRequiredNotes
files...yes
OptionNotes
--space &lt;id&gt;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]
OptionNotes
--space &lt;id&gt;space id, public link, or copied URL (default: the first target in .cloudtifact.json)
--toonprint TOON (compact, for agents)
--jsonprint JSON

sources

List a space's "Files the AI reads" (chats, emails, PDFs, images...); get one with download --source

cloudy sources [options]
OptionNotes
--space &lt;id&gt;space id, public link, or copied URL (default: the first target in .cloudtifact.json)
--toonprint TOON (compact, for agents)
--jsonprint JSON

capabilities

What a page can do (database, guest writes, ...): when to use each, how, and its docs page

cloudy capabilities [options]
OptionNotes
--space &lt;id&gt;space id, public link, or copied URL: also say which are on in that space
--toonprint TOON (compact, for agents)
--jsonprint 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]
ArgumentRequiredNotes
namenothe upload's name or id
OptionNotes
--file &lt;path&gt;download a pushed file instead (path in the space)
--source &lt;name&gt;download one of the space's "Files the AI reads" instead (name or id; see sources)
--at &lt;n&gt;with --file: the version to download from (default: latest)
-o, --output &lt;path&gt;where to save it (default: the file's name, in the current folder)
--forceoverwrite an existing file
--space &lt;id&gt;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]
ArgumentRequiredNotes
sqlnothe SQL to run (or use -f)
OptionNotes
-f, --file &lt;path&gt;read the SQL from a file (files over 100 KB are split by statement; needs --write)
--param &lt;value&gt;bind the next ? placeholder (repeatable; sent as strings)
--writeallow writes and schema changes (needs push access)
--space &lt;id&gt;space id, public link, or copied URL (default: the first target in .cloudtifact.json)
--toonprint TOON (compact, for agents)
--jsonprint 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]
OptionNotes
--space &lt;id&gt;space id, public link, or copied URL (default: the first target in .cloudtifact.json)
--toonprint TOON (compact, for agents)
--jsonprint JSON

db export

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

cloudy db export [options]
OptionNotes
-o, --output &lt;file&gt;write to this file instead of stdout
--space &lt;id&gt;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]
OptionNotes
-y, --yesdon't ask for confirmation
--space &lt;id&gt;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]
OptionNotes
--at &lt;time&gt;ISO 8601 time, e.g. 2026-09-28T10:00:00Z (or Unix ms)
-y, --yesdon't ask for confirmation
--space &lt;id&gt;space id, public link, or copied URL (default: the first target in .cloudtifact.json)
--toonprint TOON (compact, for agents)
--jsonprint JSON

db writes

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

cloudy db writes [options]
OptionNotes
-n, --limit &lt;n&gt;how many (default 100, max 500)
--space &lt;id&gt;space id, public link, or copied URL (default: the first target in .cloudtifact.json)
--toonprint TOON (compact, for agents)
--jsonprint 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]
OptionNotes
--space &lt;id&gt;space id, public link, or copied URL (default: the first target in .cloudtifact.json)
--toonprint TOON (compact, for agents)
--jsonprint JSON

db migrate

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

cloudy db migrate [options]
OptionNotes
--space &lt;id&gt;space id, public link, or copied URL (default: the first target in .cloudtifact.json)
--dir &lt;folder&gt;folder holding db/ (default: the linked repo's docs folder, else the current one)
--dry-runlist 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]
OptionNotes
--claudeClaude Code: .claude/settings.json PostToolUse
--codexCodex: .codex/hooks.json PostToolUse (apply_patch)
--cursorCursor: .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]
OptionNotes
--rulesremove 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]
OptionNotes
--checkonly 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]
OptionNotes
--toonprint TOON (compact, for agents)
--jsonprint JSON

upgrade

Update the CLI to the latest version (when it was installed with the install script)

cloudy upgrade [options]
OptionNotes
--undogo back to the CLI the last upgrade replaced (run again to switch back)