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 opening the app.

New workspaces are private. The command prints a link, but until you share it that link only works for you. The command says so on stderr, with the URL of the sharing panel. Pass --public to make a new workspace readable by anyone with the link, or set sharing 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 sign in again even if you are 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, with a file-tree sidebar and a document switcher, the same as 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. There is no new URL each time, and republishing never changes sharing you have already set up. --public only applies when the workspace is first created. A folder publish includes your vizzy.config theme and detected git-repo link.

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	Do not copy the link to the clipboard (it is 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 without prompting:

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

Leave out --public if the docs should not be world-readable. The first run then creates a private workspace. Share it or code-protect it once, and every later CI run leaves that setting alone.

The token is resolved in this 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.

Next steps

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