CLI Tool

The specdown CLI gives you a local, Git-like way to read, edit, sync, and publish SpecDown content from the terminal. It supports single-file commands, linked-folder sync, and image uploads for docs.

Installation

npm (recommended)

npm install -g specdown-cli

npx (no install)

npx specdown-cli --help

Authentication

Login

specdown login

You'll be prompted for your email and password. Session tokens are saved to ~/.specdown/config.json.

Logout

specdown logout

Check current user

specdown whoami
# → user@example.com
# → ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# → Project: my-api-docs (my-api-docs)

Project Management

List projects

specdown projects
# * my-api-docs   (active)
#   team-handbook
#   mobile-spec

Switch active project

specdown use my-api-docs

The active project is used as the default for single-file commands and image uploads.

Link a local folder to a project

# Link the current folder to a project
specdown link my-api-docs

# Link a different local folder
specdown link my-api-docs --dir ./docs

# Link only a remote subtree
specdown link my-api-docs --prefix /guides

Linking creates .specdown/project.json inside the chosen folder. That manifest stores the project, remote prefix, and sync settings for Git-like workflows.

Remove a linked folder

specdown unlink
specdown unlink --dir ./docs

Linked Folder Sync

Linked-folder mode turns a local Markdown folder into a working copy of your SpecDown project. The CLI tracks the last synced snapshot in .specdown/sync-state.json so it can detect local-only changes, remote-only changes, and conflicts.

Check sync status

specdown status
specdown status --dir ./docs

Inspect planned changes

specdown diff
specdown diff --dir ./docs

diff shows what would be pushed, pulled, created, deleted, or blocked as a conflict before you mutate either side.

Run bidirectional sync

# Apply non-conflicting changes in both directions
specdown sync

# Continuous sync for a linked folder
specdown sync --watch --yes

# Keep syncing non-conflicting changes even when conflicts exist
specdown sync --force --yes

sync is the bidirectional counterpart to directional push and pull. It applies non-conflicting local and remote changes in one run. In watch mode, the CLI re-runs the sync after debounced file changes and never overlaps two sync runs.

Push a linked folder

# Push the linked folder after confirmation
specdown push

# Non-interactive automation
specdown push --yes

# Overwrite remote when conflicts exist
specdown push --force

# Use another linked directory
specdown push --dir ./docs

Pull a linked folder

# Pull remote changes into the linked folder
specdown pull

# Non-interactive automation
specdown pull --yes

# Overwrite local conflicts with remote content
specdown pull --force

Single-File Document Operations

List documents

specdown ls
# my-api-docs
# ├── 📁 guides
# │   ├── 📄 authentication   guides/authentication
# │   └── 📄 endpoints        guides/endpoints
# └── 📄 changelog            changelog

Read a document

# Full document
specdown read guides/authentication

# Lines 10-25 only
specdown read guides/authentication --from 10 --to 25

# With line numbers
specdown read guides/authentication -n

# Pipe to another tool
specdown read changelog | grep "v2"

read prints raw Markdown to the terminal. Use line ranges to feed only the relevant section into an AI prompt or shell pipeline.

Push a local file

# Upload local file to a doc path
specdown push ./README.md changelog

# If the doc doesn't exist, it is created
specdown push ./auth-spec.md guides/authentication

Pull a document

# Download to file
specdown pull guides/authentication ./auth.md

# Print to stdout
specdown pull changelog

Create a new document or folder

# New document
specdown new "OAuth Flow"

# New document inside a folder
specdown new "OAuth Flow" --parent guides

# New folder
specdown new "API Reference" --folder

Delete a document

# With confirmation prompt
specdown rm guides/old-api

# Skip confirmation
specdown rm guides/old-api --force

Upload an image

# Upload an image and print the markdown link
specdown image ./architecture.png

# Associate the upload with a specific document
specdown image ./diagram.png --doc /guides/authentication.md

The command uploads a local image, stores it in SpecDown, and prints a Markdown image reference you can paste into any document.

Project attachments

# Upload a project file. HTML/HTM becomes editable; other files print an embed reference
specdown file upload ./assets/login-flow.png /assets/login-flow.png
specdown file upload ./pages/landing.html /pages/landing.html

# List project attachments
specdown file list
specdown file list /assets

# Read text-like files or print metadata/download info for binary files
specdown file read /assets/config.json
specdown file read /assets/login-flow.png ./login-flow.png

Use file upload for PDFs, images, videos, CSV files, and text-like files that should appear in the file tree. HTML/HTM files become editable documents; other uploaded files become preview-only attachments that Markdown documents can embed with [@/path/to/file].

Comments

Read comment threads on any document, including anchored comments left by viewers in the share view. Anonymous comments show as Anonymous; signed-in commenters show their name.

# List all threads + replies on a document
specdown comments list guides/authentication

# Hide resolved threads
specdown comments list guides/authentication --unresolved

# JSON output for scripting / AI consumption
specdown comments list guides/authentication --json

The output groups replies under their parent and prints the highlighted selection (the quoted text the comment is anchored to) above each thread.

AI Skills

SpecDown ships a bundle of AI assistant skills (Anthropic SKILL.md format) so any agent — Claude Code, Cursor, Codex, OpenCode, Antigravity, or a generic .agents/ tool — can pick up project-specific workflows without you writing prompts from scratch.

# Install for the AI tool detected in cwd (interactive prompt)
specdown install skills

# Non-interactive: pick the target explicitly
specdown install skills --for claude
specdown install skills --for cursor
specdown install skills --for codex

# Inspect bundled and cached skills
specdown skills status

On every run, the installer refreshes ~/.specdown/skills/ from the version bundled with your installed CLI, then copies into the AI tool's expected directory (.claude/skills/, .cursor/rules/ as flattened .mdc,.codex/skills/, etc.). Re-run after npm i -g specdown-cli@latestto pick up newer skill versions.

Search

# Search across all documents in the project
specdown search "rate limiting"

# Search in specific files only
specdown search "TODO" --files "guides/api,changelog"

# More context lines around matches
specdown search "authentication" -C 5

Matches are highlighted in the terminal with surrounding context lines.

Command Reference

Using in CI/CD

Set credentials as environment variables to avoid interactive prompts:

# GitHub Actions example
- name: Sync docs to SpecDown
  env:
    SPECDOWN_EMAIL: ${{ secrets.SPECDOWN_EMAIL }}
    SPECDOWN_PASSWORD: ${{ secrets.SPECDOWN_PASSWORD }}
  run: |
    npx specdown-cli login
    npx specdown-cli use my-api-docs
    npx specdown-cli link my-api-docs --dir ./docs
    npx specdown-cli sync --dir ./docs --yes

Use Cases & Tips

Let AI operate your Markdown specs

The CLI is designed to be AI-friendly. Because it runs in the terminal and prints plain text, coding agents can call it directly as a shell tool and keep a local working copy in sync with SpecDown.

# AI agent workflow
specdown link my-api-docs --dir ./specs
specdown status --dir ./specs
specdown read api/authentication
specdown image ./screenshots/login.png --doc /api/authentication.md
specdown sync --dir ./specs --yes

Preview sync before forcing changes

specdown status --dir ./docs
specdown diff --dir ./docs

# Only after reviewing the plan:
specdown sync --dir ./docs --yes
# or
specdown pull --dir ./docs --force --yes

This is the safest workflow when local edits and remote edits may have diverged.

Add screenshots and diagrams from the terminal

specdown image ./artifacts/sequence-diagram.png --doc /guides/authentication.md
# -> ![sequence-diagram.png](/r/your-project/...png)

The command returns Markdown you can insert into a doc, commit to a PR comment, or feed back into an AI-generated document update.

Edit locally, publish to SpecDown

# Edit in your local editor
code ./docs

# See what changed
specdown diff --dir ./docs

# Keep local and remote aligned
specdown sync --dir ./docs

Keep a local mirror hot while you work

# Start one watch loop per linked folder
specdown sync --dir ./docs --watch --yes

This is useful when an AI agent or editor is updating local Markdown while teammates are also editing through the web app. Non-conflicting changes are synced automatically; conflicts are kept for review.

Pull a single document into another tool

# Download a doc to a local file
specdown pull /api/overview.md ./README.md

# Send a focused section to another shell command
specdown read /api/overview.md --from 20 --to 60 | sed -n '1,12p'

Tips & Tricks

• Use linked folders for ongoing work: link, status, diff, then directional push or pull.
• Use sync for day-to-day mirroring: it applies both local and remote non-conflicting changes in one run.
• Use single-file mode for scripts: keep push <file> <doc-path> and pull <doc-path> [out-file] for small automation steps.
• Review before overwrite: run diff first. Reserve --force for cases where you intentionally want to win conflicts in one direction.
• Watch mode is automation-first: run specdown sync --watch --yes so the watcher does not block on repeated confirmation prompts.
• Use line ranges: --from and --to keep AI prompts smaller and more precise.
• Attach images to the right doc: use specdown image --doc /path when you want the asset associated with a specific document.