elephant-md

The elephant.md CLI — publish, pull, install, and share markdown from your terminal.

Install

# Zero-install (works immediately)
npx elephant-md <command>

# Or install globally for the shorter `tusk` command
npm i -g elephant-md

Quick Start

# Authenticate with GitHub
npx elephant-md login

# Publish a document
npx elephant-md push README.md

# Pull someone's document
npx elephant-md pull @username/my-doc

# Install an AI skill into your agent's context
npx elephant-md install @username/my-skill

# Configure the MCP server for your AI agent
npx elephant-md install --mcp

Commands

Publishing

push <file...>

Publish or update one or more markdown files.

npx elephant-md push guide.md
npx elephant-md push guide.md --public --tags "react,hooks"
npx elephant-md push docs/*.md --batch

| Flag | Description | |------|-------------| | --public | Make the document public | | --private | Make the document private | | --name <title> | Override document title (single file only) | | --slug <slug> | Custom URL slug | | --category <cat> | Category: skills, specs, templates, guides, data, standards, tasks, plans | | --tags <t1,t2> | Comma-separated tags | | --forked-from <@user/slug> | Mark as a fork of another document | | --to <collection> | Add to a collection after publishing | | --batch | Batch mode for multiple files (auto-enabled for 2+ files) |

Title is derived from the first # heading in the file, or the filename if none is found. Skill files (.claude/skills/*/SKILL.md) are auto-detected and categorized as skills.

list

List your published documents.

npx elephant-md list

Pulling & Installing

pull <@user/slug>

Download a document to a local file.

npx elephant-md pull @username/my-doc
npx elephant-md pull @username/my-doc --output notes.md
npx elephant-md pull @username/my-skill --skill

| Flag | Description | |------|-------------| | --output <file> | Custom output filename | | --skill | Install as a Claude skill in .claude/skills/<slug>/SKILL.md |

install <@user/slug>

Install a document into your AI agent's context directory.

npx elephant-md install @username/my-skill
npx elephant-md install @username/my-skill --agent cursor
npx elephant-md install @username/my-skill --skill

| Flag | Description | |------|-------------| | --agent <type> | Target agent: claude, cursor, windsurf, generic (auto-detected if omitted) | | --skill | Install as a Claude skill with YAML frontmatter |

Agent directories: claude → .claude/, cursor → .cursor/, windsurf → .windsurf/, generic → .ai/context/.

install --mcp

Configure the elephant.md MCP server for your AI agent.

npx elephant-md install --mcp
npx elephant-md install --mcp --agent claude

Supported agents: Claude (.mcp.json), Cursor, Windsurf.

update

Check for and apply upstream updates to installed documents.

npx elephant-md update @username/my-skill
npx elephant-md update --all

| Flag | Description | |------|-------------| | --all | Update all installed documents |

Sharing

share <file>

Create an ephemeral (self-destructing) link from a markdown file.

# View-once — destroyed after first read
npx elephant-md share secret.md --mode viewonce

# Timed — auto-expires after the given duration
npx elephant-md share notes.md --mode timed --ttl 1h
npx elephant-md share notes.md --mode timed --ttl 24h
npx elephant-md share notes.md --mode timed --ttl 7d
npx elephant-md share notes.md --mode timed --ttl 30d

| Flag | Description | |------|-------------| | --mode <timed\|viewonce> | Sharing mode (required) | | --ttl <1h\|24h\|7d\|30d> | Time-to-live (required for timed mode) |

Discovery

search <query>

Search public documents.

npx elephant-md search "react hooks"

trending

Show trending documents.

npx elephant-md trending

Bookmarks & Collections

save <@user/slug>

Bookmark a document, optionally adding it to a collection.

npx elephant-md save @username/my-doc
npx elephant-md save @username/my-doc --to my-collection

unsave <@user/slug>

Remove a bookmark.

npx elephant-md unsave @username/my-doc

bookmarks

List your bookmarked documents.

npx elephant-md bookmarks

collections

Manage your collections.

# List all collections
npx elephant-md collections list

# Create a new collection
npx elephant-md collections create "My Collection" --public
npx elephant-md collections create "Private Notes" --private --description "Personal reference"
npx elephant-md collections create "Shared Docs" --unlisted

# Show collection contents
npx elephant-md collections show my-collection

# Add or remove documents
npx elephant-md collections add my-collection @username/my-doc
npx elephant-md collections remove my-collection @username/my-doc

# Delete a collection
npx elephant-md collections delete my-collection

# Push and add to collection in one step
npx elephant-md push guide.md --to my-collection
npx elephant-md push docs/*.md --to my-collection

create flags:

| Flag | Description | |------|-------------| | --public | Make the collection public | | --unlisted | Make the collection unlisted (default) | | --private | Make the collection private | | --description <text> | Set a description for the collection |

Authentication

login

Authenticate with elephant.md.

npx elephant-md login           # GitHub (default)
npx elephant-md login github    # GitHub explicitly
npx elephant-md login google    # Google OAuth

GitHub uses device flow — opens your browser and shows a code to enter. Token is saved to ~/.tusk/config.json.

whoami

Show the currently authenticated user.

npx elephant-md whoami

Configuration

Auth token and settings are stored at ~/.tusk/config.json, managed automatically via login. Installed document state is tracked in ~/.tusk/installs.json.

Links

• elephant.md
• VS Code Extension
• GitHub