JotBird CLI – Publish Markdown from the terminal

Reference

CLI Documentation

Everything you need to know about the JotBird CLI.

Install the JotBird CLI globally with npm. Requires Node.js 18 or later.

npm install -g jotbird

Verify the installation:

jotbird --version

Link your JotBird account by running the login command. This is a one-time setup.

jotbird login

The CLI will open your browser to authenticate. Once you sign in, the CLI automatically receives your API key — no copy-pasting required.

Your token is stored locally on your machine. You won't need to log in again unless you revoke the key.

Publish a new Markdown document or update an existing one. Free accounts get 90-day links. Pro makes links permanent.

jotbird publish meeting-notes.md

Supported file types: .md, .markdown, .mdx, .txt, .text, and files without an extension (e.g. README). You can also pipe any Markdown content via stdin (see below).

The CLI creates a .jotbird file in your working directory to track which files map to which published slugs. Running the same command again updates the existing document in place — same URL, fresh content.

# First publish → creates new document
jotbird publish README.md
✨ Published → share.jotbird.com/bright-calm-meadow

# Second publish → updates in place
jotbird publish README.md
✓ Updated → share.jotbird.com/bright-calm-meadow

Local images referenced in your Markdown (e.g. ![photo](./images/photo.png)) are automatically uploaded and hosted when you publish. Your original file is not modified. Supported formats: PNG, JPEG, GIF, WebP, SVG (max 10 MB each).

To update a specific document by its slug — regardless of file tracking — use the --slug flag:

jotbird publish --slug bright-calm-meadow meeting-notes.md

This replaces the content at share.jotbird.com/bright-calm-meadow with the contents of meeting-notes.md. The --slug flag also works with stdin:

echo "# Updated content" | jotbird publish --slug bright-calm-meadow

This is useful when you know the slug but don't have a .jotbird mapping file — for example, when updating from a CI pipeline or a different machine.

View all your published documents.

jotbird list

bright-calm-meadow   Meeting Notes
                     share.jotbird.com/bright-calm-meadow

swift-red-fox        README
                     share.jotbird.com/swift-red-fox

Documents published via the CLI also appear in the web app, where you can view them and share the link. Editing is only available through the CLI — the web app shows CLI-published documents as read-only.

Pro users with a username set in Account Settings can publish at permanent, human-readable URLs like share.jotbird.com/@username/my-page. Use --namespace instead of --slug:

jotbird publish --namespace my-page notes.md
✨ Published → share.jotbird.com/@username/my-page

The --namespace flag also works with stdin:

echo "# Updated" | jotbird publish --namespace my-page

The .jotbird mapping records the full @username/slug path, so subsequent publishes without any flags update the same namespaced URL automatically. Namespaced documents also appear as @username/slug in jotbird list output:

jotbird publish notes.md
✓ Updated → share.jotbird.com/@username/my-page

To remove a namespaced document, use the --namespace flag or pass the full @username/slug form directly:

jotbird remove --namespace my-page
jotbird remove @username/my-page

Permanently delete a document from your account. This removes the public URL, stored content, and all associated data. You can pass either the original filename or the slug.

jotbird remove meeting-notes.md
jotbird remove bright-calm-meadow

The CLI tracks file-to-slug mappings in a .jotbird file in your working directory. Each line maps a filename to its published slug:

meeting-notes.md = bright-calm-meadow
README.md = swift-red-fox
blog-post.md = @username/my-post

This file is created automatically on first publish and updated on subsequent publishes. It allows jotbird publish meeting-notes.md to update the existing document without needing --slug. Namespaced documents (Pro) are stored as @username/slug and update automatically on subsequent publishes. You can commit .jotbird to version control so that collaborators and CI pipelines update the same documents.