Install
npm install -g notdocsThe package and the binary are both notdocs; npx notdocs … works without installing. It talks to a local daemon by default, or to a hosted workspace once a checkout is linked.
Global options
Each can also come from the environment.
| Option | Environment | Meaning |
|---|---|---|
--url <url> | NOTDOCS_URL | API base url; default from .notdocs/link.json or the local daemon |
--token <token> | NOTDOCS_TOKEN | Project API token |
--project <id> | NOTDOCS_PROJECT | Project; default from the link file, else inferred when exactly one is visible |
--branch <name> | Branch to read and write; default the project's | |
--json | Print JSON instead of tables and markdown | |
--idempotency-key <key> | Send the command's writes with this key, so running the same command again with the same key writes nothing twice: the first write takes the key as given, the ones after it <key>.2, <key>.3 and on. Without it each write gets a key of its own. See Retrying a write |
Global options may come before or after the subcommand.
Set up
| Command | What it does |
|---|---|
notdocs init [folder] | Create notdocs.config.json, a docs folder and agent instructions, and list the markdown the workspace would not read. --include reads it where it is (include globs), with --agent-files the coding agents' files too; --move shows how it would move into the docs root and --move --apply moves it, keeping each file's path below the root and rewriting the links to and from the moved files (refused in a checkout with uncommitted changes). The agents' files never move |
notdocs serve [folder] | Run the local daemon: HTTP API, websocket feed and index for one folder. --port <port> (default 4400), --data-dir <dir> (default <folder>/.notdocs/index), --token <token> (or NOTDOCS_DAEMON_TOKEN): web pages must present it, as a bearer token on every request carrying an Origin header and as ?token= on the websocket; the CLI and the MCP server are not asked |
notdocs mcp | Model Context Protocol server on stdio, one tool per operation. --serve <folder> also runs an in-memory daemon on that folder |
notdocs link | Point this checkout at a hosted workspace: writes .notdocs/link.json with --url, --project and, only if given, --token |
notdocs unlink | Remove the link file above the working directory |
notdocs status | Where commands are pointed: url, project, token and how each was chosen |
Resolution order for url, project and token: flags, NOTDOCS_* variables, the link file, the local daemon.
Documents
| Command | What it does |
|---|---|
notdocs docs list | List documents on the branch. --type <type>, --path <prefix> |
notdocs docs get <ref> | Print the markdown of a document, by id or path |
notdocs docs new <path> | Create a document. --title <title>, --template <name>, --set key=value… |
notdocs docs set <ref> <key=value…> | Change frontmatter keys, merging with what is on disk |
notdocs docs edit <ref> | Open the document in $EDITOR and save it back |
notdocs docs restore <ref> <hash> | Put a document back to an earlier version, by the hash notdocs changes prints; the restore is recorded as a new change. Exits 5 if the document changed meanwhile |
notdocs docs backlinks <ref> | List the documents that link to one, by [[wikilink]] or by path |
notdocs docs export <ref> | Export a business document. --format docx (default) or html, --out <file> |
notdocs assets upload <file> | Store an image and print the markdown that shows it. --alt <text>. The plan's cap is checked before the file is sent; on the hosted service the image goes straight to the store, as from the web app. |
notdocs docs mv <ref> <newPath> | Move or rename a document; its id, history and comments stay with it, and the links to it in other documents are rewritten in the same commit |
notdocs docs mkdir <folder> | Create a folder under the docs root as <folder>/index.md, since git keeps no empty folders. --title <title> |
notdocs docs rm <ref> | Delete a document |
notdocs publish <ref> [level] | Who may read a document or a folder without an account: public (listed on the published site), link (anyone with its address), private, or inherit to drop its own setting. A folder is set on its index.md, made when it has none. Without a level, prints the setting, where it comes from and the address |
notdocs publish --project-default <level> | The project's default, visibility in notdocs.config.json; inherit takes the organization's. --org-default <level> sets the organization's |
notdocs docs organize | Show how the markdown include reads outside the docs root would move under it, each keeping its path below the root. --apply moves it in one commit (links rewritten), drops the include globs the move emptied, checks the links before and after, and exits 1 if the move left a link reaching nothing |
Workspace
| Command | What it does |
|---|---|
notdocs projects | List the projects this token can see |
notdocs projects delete <slug> | Delete the project for good (index, feed, versions, guests, tokens, assets); the slug is the confirmation and the repository is not touched |
notdocs branches | List branches of the project |
notdocs config | Show notdocs.config.json: the docs root, root files, include globs, agent files, ignore globs, types |
notdocs config survey | Find the markdown the workspace does not read: each top-level folder or root file with its count and the include glob that reads it where it is, the coding agents' files apart, and the formats it does not read (.markdown; .md, .mdd, .mdc and .mdx are read). --apply adds the globs to include and re-indexes; --agent-files with it reads the agents' files too |
notdocs config set | Change it and re-index the branch. --docs-root <path>, --include <globs…> (markdown read where it is), --agent-files / --no-agent-files, --ignore <globs…>; a list replaces the one in the file, and other keys are kept. Newly read files get an id, which on GitHub is one commit |
notdocs query <query> | Run a query block, given as YAML or JSON, and print its groups |
notdocs search <q> | Full-text and semantic search. --limit <n> |
notdocs changes | Print the change feed, each line ending with the version's hash. --since <seq>, --tail <n> (with --doc <id or path> for one document's history), --follow |
notdocs templates | List document templates |
notdocs validate <ref> | Check a document against its type schema and, for a business document, its MDD structure |
notdocs links | Check every link, image and wikilink on the branch and list the ones that reach nothing, by document and line; exits 1 when there are any, so it can gate CI. Anchors and links to other sites are not checked |
notdocs lint [--fix] | Find the markdown on the branch that renders as text instead of what it is: pipe rows GFM does not read as a table (a delimiter row wider or narrower than the header, or none), a file tree outside a code block, Mermaid source outside a code block or in a fence with no language, and a code block that holds the start of another, which makes the fences after it pair up wrong. Exits 1 when there are any. --fix repairs all but the fences in one commit, changing only the lines at fault |
notdocs reindex | Re-index the branch: stamp ids, rebuild search and embeddings |
notdocs op <name> [json] | Run any operation in the contract; input as JSON or from stdin |
Import
| Command | What it does |
|---|---|
notdocs import notion <source> | Import a Notion "Markdown & CSV" export, a .zip or an unzipped folder; its images are uploaded and the pages point at them. --into <folder> (default docs/notion), --dry-run |
notdocs import obsidian <source> | Import an Obsidian vault, a .zip or a folder; its images are uploaded and the pages point at them. --into <folder> (default docs), --dry-run |
notdocs import docx <files...> | Import Word documents, one page each, pictures stored as images. --into <folder> (default docs), --title <title> for one file |
Comments
| Command | What it does |
|---|---|
notdocs comments <ref> | List comment threads on a document. --unresolved |
notdocs comment <ref> <body> | Start a thread. --anchor <slug> ties it to a heading |
notdocs reply <ref> <threadId> <body> | Reply to a thread |
notdocs resolve <ref> <threadId> | Resolve a thread |
People and tokens
| Command | What it does |
|---|---|
notdocs token create --name <name> | Create a scoped API token; --scope read or write (default). --path <folder> (repeatable) limits a write token to writing under those folders, as paths from the repository root; it reads the whole project either way. The secret is printed once |
notdocs token list | List agent tokens with the folders each is limited to; secrets are never shown |
notdocs token revoke <id> | Revoke a token immediately |
notdocs members | List members and guests of the project |
notdocs members role <email> <member|guest> [--docs ids] | Change a person's access; owners are not changed here |
notdocs members remove <email> | Remove a person from the organization: membership and every guest access |
notdocs invite <email> | Add a person. --role member or guest; --docs <ids> limits a guest to specific documents |
Organization
| Command | What it does |
|---|---|
notdocs org slug <slug> | Rename the organization slug, which is its subdomain when hosted |
notdocs org domain set <domain> | Register a custom domain for the published documents and print the DNS records to create |
notdocs org domain status | Verification state of the custom domain and the records still missing |
notdocs org domain remove | Stop serving the organization's published documents on its custom domain |
notdocs org delete <slug> | Delete the organization for good with its projects, people and custom domain; refused while a paid plan is set to renew (cancel it first) |
notdocs org plan | The organization's plan, what it allows and what is used |
notdocs org upgrade <solo|team> | Start a checkout for a paid plan; prints the URL to open |
notdocs org billing | Print the billing portal URL: invoices, payment method, cancellation |