cmdmark

Store reusable shell commands in Markdown, fill in placeholders, preview, and run them safely.

The root COMMANDS.md includes public HTTP examples that assume curl and jq are available.

This package is MIT licensed.

Command shape

Commands live in COMMANDS.md:

<!-- cmd:github-repo -->
<!-- param:owner openai|nodejs|vercel|<custom> -->
<!-- param:repo openai-node|node|next.js|<custom> -->
```sh
curl -sS "https://api.github.com/repos/{{owner}}/{{repo}}" \
  | jq '{full_name, description, stars: .stargazers_count}'
```
<!-- /cmd -->

• cmd:github-repo makes the command selectable by ID.
• The first sh, bash, shell, zsh, or unlabeled code fence is the command.
• {{owner}} and {{repo}} are prompted at runtime.
• param: comments turn placeholder prompts into searchable option lists.
• $ENV_VAR references are normal shell environment variables. When running a command, cmdmark also loads a .env file beside the loaded command file if one exists. Shell environment values override .env values.
• cmdmark sets $CMDMARK_FILE and $CMDMARK_DIR when it runs a command.

Quick start

Create a starter command file:

npx cmdmark@latest init

Open the searchable picker:

npx cmdmark@latest

Run a command directly:

npx cmdmark@latest run hello name=world

Common commands:

npx cmdmark@latest list
npx cmdmark@latest print hello name=Nick
npx cmdmark@latest run hello name=Nick
npx cmdmark@latest run --yes hello name=Nick
npx cmdmark@latest lint

If there is no COMMANDS.md in the current directory, interactive use offers to create a starter file. You can also create one directly:

npx cmdmark@latest init
npx cmdmark@latest --file docs/COMMANDS.md init

Local development

nvm use
npm install
npm start -- list
npm start -- --version
npm start -- init
npm start
npm start -- print github-repo owner=openai repo=openai-node
npm start -- run github-repo owner=openai repo=openai-node
npm start -- run --yes github-search-repos language=javascript topic=cli limit=3
npm start -- lint

You can also run the binary directly:

./bin/cmdmark.js
./bin/cmdmark.js --version
./bin/cmdmark.js init
./bin/cmdmark.js print github-repo owner=openai repo=openai-node
./bin/cmdmark.js run github-repo owner=openai repo=openai-node

Running cmdmark with no subcommand opens a searchable picker. Start typing a command ID, like github, to filter the list.

Before execution, cmdmark previews the rendered command and prompts for:

• y to run it
• n to cancel
• e to edit the command inline before deciding again

Preview output is syntax-highlighted when the command fence has a language like sh, bash, shell, or zsh. The language label is optional; unlabeled fences work too. print stays plain for copying and piping. Set NO_COLOR=1 to disable preview colors.

Use --yes or -y with run to skip preview and confirmation.

Placeholder Options

Use param: comments inside a command block to define options for a placeholder:

<!-- cmd:github-issues -->
<!-- param:state open|closed|all -->
<!-- param:limit 5|10|25|50|<custom> -->
```sh
curl "https://api.github.com/repos/openai/openai-node/issues?state={{state}}&per_page={{limit}}"
```
<!-- /cmd -->

• <!-- param:state open|closed|all --> locks state to those options.
• <!-- param:limit 5|10|25|50|<custom> --> lets the user pick an option or choose <custom> and type another value.
• The option prompt is searchable; start typing to filter the available values.
• name=value CLI arguments still bypass prompts.

By default, it reads COMMANDS.md in the current directory. To use another file:

./bin/cmdmark.js --file ./docs/COMMANDS.md list

cmdmark reads one command file at a time. If a repo has both a root COMMANDS.md and a nested examples/COMMANDS.md, the current directory decides which one is used by default:

cmdmark list                         # reads ./COMMANDS.md
cd examples && cmdmark list          # reads examples/COMMANDS.md
cmdmark --file examples/COMMANDS.md list

When a command runs, $CMDMARK_DIR points to the directory containing the loaded Markdown file, not necessarily the shell's current directory. Use it for files that live next to a command file:

sqlite3 "$CMDMARK_DIR/demo.db" "SELECT * FROM users;"

SQLite example

The examples/ directory includes a tiny seeded SQLite database and an example command file. It also includes a committed demo .env file with fake API values. The SQLite commands use $CMDMARK_DIR/demo.db, and the curl commands use $API_BASE_URL plus $API_TOKEN from examples/.env, so they work from the repo root or from inside examples/:

./bin/cmdmark.js --file examples/COMMANDS.md list
./bin/cmdmark.js --file examples/COMMANDS.md print sqlite-list-users
./bin/cmdmark.js --file examples/COMMANDS.md print sqlite-list-query-values
./bin/cmdmark.js --file examples/COMMANDS.md print sqlite-get-user user_id=2
./bin/cmdmark.js --file examples/COMMANDS.md print sqlite-find-users role=developer status=active limit=10
./bin/cmdmark.js --file examples/COMMANDS.md run sqlite-update-user-status user_id=3 status=active
./bin/cmdmark.js --file examples/COMMANDS.md run --yes api-find-users role=admin status=active limit=5
./bin/cmdmark.js --file examples/COMMANDS.md run --yes api-create-user name=Nick [email protected] role=admin status=active

The same file also includes curl examples with multiple placeholder values in query parameters and JSON request bodies.

For local development, link the package if you want the cmdmark command on your PATH:

npm link
cmdmark list

Publishing

Before publishing:

npm test
git diff --check
npm pack --dry-run

The package uses a files whitelist so npm ships only the CLI, source, documentation, license, and examples.