mdpush

Push markdown files to Preview Reader from your terminal.

Install

npm install -g mdpush

Or use directly with npx (no install needed):

npx mdpush setup

Quick Start

# 1. Run interactive setup (server URL, API token, default project)
mdpush setup

# 2. Push a file
mdpush push README.md

# 3. Push to a specific project
mdpush push -p my-project docs/*.md

Commands

mdpush setup

Interactive wizard to configure server, token, and default project. Validates your token against the server before saving. Optionally installs the Claude Code skill.

mdpush push [files...]

Upload .md, .txt, and .html files to a project. HTML files are hosted at /v/:sid as sandboxed artifacts with an optional --type tag.

| Flag | Description | |------|-------------| | -p, --project <slug> | Target project (falls back to default from setup) | | -f, --folder <path> | Subfolder within the project (md/txt only — HTML artifacts are flat) | | -t, --type <value> | HTML artifact type: spec | review | design | report | playground (HTML files only) |

mdpush push README.md                              # Uses default project
mdpush push -p docs-site *.md                      # Specific project
mdpush push -p docs-site -f guides plan.md         # Into subfolder
mdpush push docs/                                  # Upload entire directory (md/txt only)
mdpush push design.html --type design              # HTML artifact with type tag
mdpush push spec.html notes.md --type spec         # Mixed batch — type applies only to .html

HTML output includes the viewer URL and type badge:

🔗 [design] https://docs.example.com/v/abc123  design.html

.md/.txt output uses the project-relative direct link:

🔗 https://docs.example.com/p/docs-site/f/xyz789  plan.md

mdpush login

Authenticate with username/password to generate an API token.

mdpush login -s https://docs.example.com

mdpush config

Show stored configuration (server, username, default project).

mdpush logout

Clear stored credentials from ~/.mdpush.json.

Claude Code Integration

During mdpush setup, if Claude Code is detected (~/.claude/skills/ exists), you'll be offered to install the mdpush skill automatically.

Once installed, use /mdpush in Claude Code to push files directly from your AI assistant.

Manual install:

mkdir -p ~/.claude/skills/mdpush/scripts
cp node_modules/mdpush/assets/SKILL.md ~/.claude/skills/mdpush/SKILL.md
cp node_modules/mdpush/assets/scripts/push.sh ~/.claude/skills/mdpush/scripts/push.sh
chmod +x ~/.claude/skills/mdpush/scripts/push.sh

Configuration

Config is stored at ~/.mdpush.json with restricted permissions (0600):

{
  "server": "https://docs.example.com",
  "token": "<api-token>",
  "username": "you",
  "defaultProject": "my-project"
}

Generate tokens from the web UI: Sidebar > API Tokens > Generate Token.

Troubleshooting

| Error | Fix | |-------|-----| | 401 Unauthorized | Token expired or revoked. Generate a new one from the web UI. | | 403 Forbidden | No write access to this project. Ask the owner to invite you. | | 404 Not Found | Wrong project slug. Check it in the web UI URL: /p/<slug> | | 413 Too Large | File exceeds 10MB (.md/.txt) or 15MB (.html) limit. | | 400 Invalid type | --type value not in whitelist. Use one of: spec, review, design, report, playground. |

Requirements

• Node.js >= 18
• A running Preview Reader server

License

MIT