Add Documents

Create a document

ctx add nodes/api-design --title "API Design Guide" --tags "engineering,api"

This creates nodes/api-design.md from a frontmatter template as version 1, and regenerates the index. Tags accept a comma- or space-separated list; you can also pass the body inline with --body, and set a node type with --type (default: document).

ctx add nodes/api-design \
  --title "API Design Guide" \
  --tags "engineering,api" \
  --type reference \
  --body "Your markdown content here"

The write receipt

Every write asks for confirmation first and then prints the exact list of files it created, modified, or deleted — nothing is overwritten silently. To see what a command would do without touching disk, add --dry-run (it runs against a temp copy of the vault and reports the real file list). In a non-interactive shell, pass --yes to skip the prompt or --force to allow overwriting.

ctx add nodes/api-design --title "API Design Guide" --dry-run

Single vs. bulk import

• Single document — ctx add <path> as above, one file at a time.
• Bulk — drop or copy a folder of markdown under the vault's data root, then bring it in as a nest, or publish everything already present in one batch with ctx publish --all (publishes every unpublished document at once).

Document format

Every Context Nest document is a Markdown file with YAML frontmatter:

---
title: "API Design Guide"
type: document
tags: ["#engineering", "#api"]
status: published
version: 1
created_at: "2026-03-15T12:00:00Z"
---

# API Design Guide

Your content here. Plain Markdown with GFM support.

## Context Links

Reference other documents: [[API Design Guide]] or by id [Architecture](contextnest://nodes/architecture-overview)

Update a document

ctx update nodes/api-design --title "API Design Standards" --body "Updated content here"

Updates auto-publish: the version is bumped, a new checkpoint is recorded, and the index is regenerated. Options: --title, --tags (replaces existing), --status, --body.

Delete a document

ctx delete nodes/api-design

Removes the document and its full version history. This is a destructive write, so it prompts for confirmation (or needs --yes/--force non-interactively).

List documents

ctx list                          # All documents
ctx list --type reference         # Filter by type
ctx list --status published       # Filter by status
ctx list --tag engineering        # Filter by tag
ctx list --limit 20               # Cap the results
ctx list --json                   # JSON output