The command line

With Node 20 or later:

npm install -g 23artifacts

or run it once without installing anything: npx 23artifacts publish ./dist.

With Homebrew:

brew trust 23made/tap
brew install 23made/tap/23artifacts

Homebrew 7 loads formulae only from taps you trust; before version 7 there is no brew trust, and the second line works alone. It runs on macOS and Linux; on Windows the npm package runs, without the promise.

$ 23a login
Opening your browser to sign in to 23artifacts.
If it does not open, go to this address:
https://23artifacts.com/api/auth/mcp/authorize?response_type=code&client_id=…

Waiting for the browser. Press Ctrl-C to stop.
Signed in as Martin May (@martin-may).

The browser asks you to let 23a on <this machine> act for you; say yes and the tab tells you it can be closed. On a machine with no browser — a server over SSH — 23a login --no-browser prints the address to open elsewhere; the browser there ends on an address that will not load, which you paste back into the terminal. The sign-in is kept in the system's keychain or secret store, and ends after a week unused. 23a whoami says who is signed in and in which workspaces; 23a logout signs this machine out.

$ 23a publish ./dist
Publishing dist/ — 14 files, 3.2 MB — as a new artifact named "Launch plan".
Version 1 is live.
Who can open it: only you.
https://k3x9p2qa.23a.so

A folder or a single file; a markdown file is published as a page. The same folder published again from the same place becomes the next version of the same artifact, and publishing what is already live makes nothing: Nothing changed: version 2 is already live. Large files are uploaded on their own, with a line that counts up. When an artifact of the same name exists and nothing says which one this is, you are asked.

Option	What it does
--to <artifact>	This artifact's next version, or a new one with that key
--new	A separate artifact, whatever matches
--name <name>	The artifact's name
--staged	Saved, not live
--dry-run	Every check, nothing written
--note <text>	How and why this version was made
--theme <theme>	The look a page or a markdown file is drawn in

An artifact is named the way every surface names one: its address, its identifier or its key.

Command	What it does
23a list [question]	The artifacts a question finds, most recently touched first, in the words the search field takes (kind:deck tag:q4)
23a open [artifact]	Its address in the browser; --manage opens its page in 23artifacts. With nothing named, the artifact this folder was published to
23a comments <artifact>	The open threads on its live version; --all adds the resolved

Every command takes --workspace <handle>, --json and --help.

What a program parses goes to standard output and what a person reads goes to standard error, so --json changes only what a program sees. With --json the command prints one JSON value, the server's answer, and never asks: a question it would have asked is a refusal naming the options that answer it (Pass --to k3x9p2qa to publish its next version, or --new for a separate artifact.).

Exit code	kind	Meaning
0		Done, a publish that changed nothing included
1	refused	The server refused, in its own words
2	usage	The command is wrong: an unknown command or option, a path naming nothing on disk, a choice it could not ask
3	signed_out	No sign-in and no credential, or a sign-in that has ended
4	unreachable	23artifacts could not be reached; nothing is half-made

A failure under --json prints {"error", "kind", "status"}.

A scheduled job or a CI run uses a credential instead of a sign-in. Mint one on your account's credentials page, keep it in the job's secrets, and set it as TTARTIFACTS_TOKEN:

export TTARTIFACTS_TOKEN="<the credential, from the job's secrets>"
npx 23artifacts publish ./dist --to launch-plan --json

The credential is never stored, wins over a sign-in, and carries exactly its scopes and its workspace: a publish-only credential publishes and lists, and a command that needs read or manage is refused saying which. Naming --to keeps a job from ever being asked which artifact it means.