Command-line client

A path-addressed, line-oriented client for a Corpus vault. It talks to the same MCP endpoint an editor does, so a token is all it needs. The commands below come from the CLI's own catalogue.

Install

Requires Node 22 or newer.

npm install -g @schupke/corpus-cli

Sign in

Store a token per server, then switch between them with a flag.

corpus login --url https://corpus.schupke.io
corpus whoami

Global options

Every command accepts these, in any position.

Flag	Type	Description
`--url`	value	server origin, or the full /api/mcp endpoint
`--token`	value	corpus_pat_… token; also read from CORPUS_TOKEN
`--profile`	value	use a named profile from the config
`--local`	flag	shorthand for --url http://localhost:4282
`--dev`	flag	use the 'dev' profile
`--prod`	flag	use the 'prod' profile
`--timeout`	value	per-request timeout in ms (default 30000; 0 disables)
`--json`	flag	print the raw payload as JSON instead of formatted records
`-0, --null`	flag	separate output records with NUL, for xargs -0
`-y, --yes`	flag	assume yes for confirmations
`-q, --quiet`	flag	suppress the stderr summaries
`--refresh`	flag	ignore the cached tool list
`--no-color`	flag	never colour stderr (NO_COLOR is honoured too)
`--verbose`	flag	print diagnostics; also enabled by CORPUS_DEBUG
`-h, --help`	flag	show this help, or a command's help
`-V, --version`	flag	print the version

Commands

Vault

corpus ls

list the entries in a folder

corpus ls [PATH] [-R] [-l] [-d|-f] [--depth N]

Flag	Type	Description
`-R, --recursive`	flag	descend into subfolders, printing full paths instead of basenames
`-l, --long`	flag	print kind and path, tab-separated
`-d, --dirs-only`	flag	list folders only
`-f, --files-only`	flag	list notes only
`--depth`	value	how many levels to descend

corpus tree

list a folder and everything under it, one path per line

corpus tree [PATH] [--depth N] [-d]

Flag	Type	Description
`--depth`	value	how many levels to descend
`-d, --dirs-only`	flag	list folders only

corpus open

print a note's markdown to stdout, byte for bytealias cat

corpus open PATH... [--header] [--ignore-missing]

Flag	Type	Description
`--header`	flag	print a ==> path <== header before each note
`--ignore-missing`	flag	skip paths that do not exist instead of failing

corpus stat

report whether a path is a note or a folder

corpus stat PATH

Takes no options of its own.

corpus search

search note names and content, grep-style

corpus search QUERY [--tag NAME]... [--limit N] [--under PATH] [-d] [--match-path] [-l] [-c] [-q]

Flag	Type	Description
`--limit`	value	maximum number of hits to return
`--under`	value	restrict the search to one folder
`-d, --dirs`	flag	include folder hits alongside note hits
`--dirs-only`	flag	return folder hits only
`--match-path`	flag	match the full vault path, not just the note name and body
`--tag`	value	only entries carrying this tag; repeatable, and all of them must match
`-l, --files-with-matches`	flag	print each matching path once, with no line numbers
`-c, --count`	flag	print the number of matches instead of the matches

corpus create

create a note, making any missing folderswrite token

corpus create PATH [--text S | --file F | -] [--force]

Flag	Type	Description
`--text`	value	take the content from this argument
`--file`	value	take the content from a local file (- for stdin)
`--force`	flag	overwrite the note when it already exists
`--allow-empty`	flag	permit empty content, which is otherwise refused

corpus mkdir

create a folder, making any missing parentswrite token

corpus mkdir PATH... [-p]

Flag	Type	Description
`-p, --parents`	flag	create missing parents, and succeed if it already exists

corpus write

overwrite a note's body from stdin, --text, or --filewrite token

corpus write PATH [--text S | --file F] [--allow-empty]

Flag	Type	Description
`--text`	value	take the content from this argument
`--file`	value	take the content from a local file (- for stdin)
`--allow-empty`	flag	permit empty content, which is otherwise refused

corpus append

append to a notewrite token

corpus append PATH [--text S | --file F | -] [--no-newline]

Flag	Type	Description
`--text`	value	take the content from this argument
`--file`	value	take the content from a local file (- for stdin)
`--no-newline`	flag	do not insert a newline before the appended text

corpus replace

substitute text inside a notewrite token

corpus replace PATH FIND SUB [--regex] [--ignore-case] [--count N] [--dry-run] [-l]

Flag	Type	Description
`--regex`	flag	treat the pattern as a regular expression, matched per line
`--ignore-case`	flag	match without regard to case
`--count`	value	stop after this many replacements
`--dry-run`	flag	report what would change without writing
`-l, --long`	flag	print each replacement as path<TAB>line<TAB>text

corpus mv

move or rename notes and foldersalias movewrite token

corpus mv SRC DEST   |   corpus mv SRC... DESTDIR/

Flag	Type	Description
`-l, --long`	flag	print each move as from<TAB>to
`--from-stdin`	flag	read the paths to act on from stdin, one per line

corpus rm

delete notes and foldersalias deletewrite token

corpus rm PATH... [-r] [-f] [-i] [--file | --dir]

Flag	Type	Description
`-r, --recursive`	flag	allow deleting a folder and everything under it
`-f, --force`	flag	ignore paths that do not exist, and never prompt
`-i, --interactive`	flag	confirm before each deletion
`--file`	flag	treat the path as a note, instead of inferring its kind
`--dir`	flag	treat the path as a folder, instead of inferring its kind
`--from-stdin`	flag	read the paths to act on from stdin, one per line

corpus versions

list a note's saved versions, newest first

corpus versions PATH

Takes no options of its own.

corpus show-version

print the markdown of one saved version

corpus show-version VERSION_ID

Takes no options of its own.

corpus restore

make a saved version current againwrite token

corpus restore VERSION_ID

Takes no options of its own.

corpus tags

list and manage the tag library

corpus tags [-l] | corpus tags add NAME [--color C] | corpus tags rm NAME | corpus tags rename OLD NEW | corpus tags color NAME C|none

Flag	Type	Description
`-l, --long`	flag	print name, colour and use counts, tab-separated
`--color`	value	hex colour for `add`, e.g. '#3b82f6'
`--unused`	flag	list only tags nothing carries

corpus tag

show or change the tags on one note or folderwrite token

corpus tag PATH [-a NAME]… [-r NAME]… [--set NAMES] [-d|-f]

Flag	Type	Description
`-a, --add`	value	add a tag, creating it if new; repeatable, or comma-separated
`-r, --remove`	value	remove a tag from this entry; the tag itself stays in the library
`--set`	value	replace the whole set with this comma-separated list
`-d, --dirs-only`	flag	treat PATH as a folder
`-f, --files-only`	flag	treat PATH as a note

Auth and profiles

corpus logout

forget a stored token

corpus logout [--dev | --prod | --profile NAME] [--all]

Flag	Type	Description
`--all`	flag	remove every stored profile, not just the current one

corpus status

show the configured server and token, without contacting it

corpus status [--dev | --prod | --profile NAME]

Takes no options of its own.

corpus whoami

report what this token can do (cached; --refresh to re-check)

corpus whoami [--dev | --prod | --profile NAME] [--refresh]

Takes no options of its own.

corpus profiles

list stored profiles

corpus profiles

Takes no options of its own.

corpus use

make a profile the default

corpus use PROFILE

Takes no options of its own.

corpus tools

list the tools this token is granted

corpus tools

Takes no options of its own.