Publishing from the CLI

vizzy publish puts a .vizzy.md file — or a whole folder — on usevizzy.com. It creates the same links as the app’s Publish menu (see Publishing on the web), so an agent or a CI job can publish without ever opening the app.

New workspaces are private. The command prints a link, but until you share it that link only works for you — and it says so on stderr, with the URL of the sharing panel. Pass --public to make a new workspace readable by anyone with the link on create, or set it up afterwards from the page itself or your library: private, password-protected, or public. See Who can read it.

Sign in

Publishing needs an account. The app and the CLI share one — sign in on either and the other is signed in too.

vizzy login          # opens your browser to sign in with GitHub
vizzy logout         # sign out and drop the stored token

vizzy login opens a browser window to authorise with GitHub and stores the resulting token in your macOS Keychain. Pass --force to re-authenticate even if you’re already signed in.

Publish

vizzy publish <file.vizzy.md | folder> [options]

• A single file publishes as its own page.
• A folder publishes every .vizzy.md (and plain .md) beneath it as one browsable workspace — a file-tree sidebar and a document switcher, exactly like the app’s Publish this workspace. Build output, vendored dependencies, and hidden folders are skipped.

The bare URL is printed to stdout (so you can pipe it) and copied to your clipboard. Republishing the same file or folder updates the same link — no new URL each time, and it never changes sharing you’ve already set up (--public only applies when the workspace is first created). A folder publish carries your vizzy.config theme and detected git-repo link along with it.

vizzy publish vizzy/auth.vizzy.md          # one document
vizzy publish vizzy/ --name "Acme Architecture"   # a whole workspace
vizzy publish vizzy/ --dry-run             # list what would be published, upload nothing

Options

Option	What it does
--public	Make a new workspace readable by anyone with the link. Ignored when republishing an existing one.
--name <name>	Workspace title and slug. Defaults to the folder name; for a single file, overrides the document’s title.
--dry-run	List the documents that would be published, then exit without uploading anything.
--open	Open the published link in your browser afterwards.
--no-copy	Don’t copy the link to the clipboard (it’s copied by default).
--token <token>	Publish token to use instead of your signed-in session (see below).
--endpoint <url>	Override the publish endpoint (default https://usevizzy.com/api/publish).

Publishing from CI

CI has no browser to sign in through, so give vizzy publish a token directly. Set VIZZY_PUBLISH_TOKEN (or pass --token) and the command runs non-interactively:

export VIZZY_PUBLISH_TOKEN="…"
vizzy publish vizzy/ --name "Acme Architecture" --no-copy --public

Drop --public if the docs shouldn’t be world-readable — the first run then creates a private workspace you share (or code-protect) once, and every later CI run leaves that setting alone.

The token is resolved in order: --token, then VIZZY_PUBLISH_TOKEN, then the session stored by vizzy login. If you run your own publish backend, point at it with --endpoint or the VIZZY_PUBLISH_ENDPOINT environment variable.

Where to next

• Publishing on the web — the app’s Publish menu, visibility and share codes, reading vs canvas mode, and managing what you’ve published from your library.