CLI Reference

Complete command reference for Knowns CLI

16 min read

Command Reference

Complete reference for all Knowns CLI commands.

Task Commands

`knowns task <id>` (Shorthand)

View a single task (shorthand for knowns task view).

knowns task <id> [options]

Option	Description
`--plain`	Plain text output (for AI)

Examples:

knowns task 42 --plain

`knowns task create`

Create a new task.

knowns task create "Title" [options]

Option	Description
`-d, --description`	Task description
`--ac`	Acceptance criterion (repeatable)
`-l, --labels`	Comma-separated labels
`--priority`	`low`, `medium`, `high`
`-a, --assignee`	Assignee (e.g., `@me`, `@john`)
`--parent`	Parent task ID for subtasks

Examples:

# Basic task
knowns task create "Fix login bug"
 
# Task with details
knowns task create "Add authentication" \
  -d "Implement JWT auth following @doc/patterns/auth" \
  --ac "User can login" \
  --ac "Session persists" \
  --priority high \
  -l "feature,auth"
 
# Subtask
knowns task create "Write unit tests" --parent 42

`knowns task list`

List all tasks.

knowns task list [options]

Option	Description
`--status`	Filter by status
`--priority`	Filter by priority
`--assignee`	Filter by assignee
`--label`	Filter by label
`--tree`	Show as tree hierarchy
`--plain`	Plain text output (for AI)

Examples:

knowns task list --plain
knowns task list --status in-progress --assignee @me
knowns task list --tree --plain

`knowns task view`

View a single task (full command form).

knowns task view <id> [options]

Option	Description
`--plain`	Plain text output (for AI)

`knowns task validate`

Validate a task file format.

knowns task validate <id> [options]

Option	Description
`--plain`	Plain text output (for AI)

`knowns task repair`

Repair a corrupted task file.

knowns task repair <id> [options]

Option	Description
`--plain`	Plain text output (for AI)

`knowns task edit`

Edit an existing task.

knowns task edit <id> [options]

Option	Description
`-t, --title`	New title
`-d, --description`	New description
`-s, --status`	`todo`, `in-progress`, `in-review`, `blocked`, `done`
`--priority`	`low`, `medium`, `high`
`-a, --assignee`	Assignee
`-l, --labels`	Labels (replaces existing)
`--ac`	Add acceptance criterion
`--check-ac`	Check criterion (1-indexed)
`--uncheck-ac`	Uncheck criterion
`--remove-ac`	Remove criterion
`--plan`	Set implementation plan
`--notes`	Set implementation notes
`--append-notes`	Append to notes

Examples:

# Change status and assignee
knowns task edit 42 -s in-progress -a @me
 
# Check acceptance criteria
knowns task edit 42 --check-ac 1 --check-ac 2
 
# Add implementation plan
knowns task edit 42 --plan $'1. Research\n2. Implement\n3. Test'
 
# Add notes progressively
knowns task edit 42 --append-notes "Completed auth middleware"

Documentation Commands

`knowns doc <path>` (Shorthand)

View a document (shorthand for knowns doc view).

knowns doc <name-or-path> [options]

Option	Description
`--plain`	Plain text output (for AI)
`--smart`	Auto-handle small/large docs (recommended)
`--info`	Show document stats (size, tokens, headings)
`--toc`	Show table of contents only
`--section <title>`	Show specific section by heading title or number

Examples:

knowns doc "README" --plain
knowns doc "patterns/auth" --plain
 
# Large document workflow with --smart (recommended)
knowns doc "README" --plain --smart
# Small doc → returns full content
# Large doc → returns stats + TOC
 
# Then read specific section
knowns doc "README" --section "2. Installation" --plain
knowns doc "README" --section "2" --plain  # By number
 
# Manual control
knowns doc "README" --info --plain      # Check size first
knowns doc "README" --toc --plain       # Get TOC

`knowns doc create`

Create a new document.

knowns doc create "Title" [options]

Option	Description
`-d, --description`	Document description
`-t, --tags`	Comma-separated tags
`-f, --folder`	Folder path (e.g., `patterns`, `architecture/api`)

Examples:

# Simple doc
knowns doc create "API Guidelines" -d "REST API conventions"
 
# Doc in folder
knowns doc create "Auth Pattern" \
  -d "JWT authentication pattern" \
  -t "patterns,security" \
  -f patterns

`knowns doc list`

List all documents.

knowns doc list [path] [options]

Argument	Description
`[path]`	Filter by folder path (e.g., `guides/`, `patterns/`)

Option	Description
`--tag`	Filter by tag
`--plain`	Plain text output (tree format, token-efficient)

Examples:

# List all docs
knowns doc list --plain
 
# List docs in specific folder
knowns doc list "guides/" --plain
knowns doc list "patterns/" --plain
 
# Filter by tag
knowns doc list --tag architecture --plain

`knowns doc view`

View a document (full command form).

knowns doc view <name-or-path> [options]

Option	Description
`--plain`	Plain text output
`--smart`	Auto-handle small/large docs (recommended)
`--info`	Show document stats (size, tokens, headings)
`--toc`	Show table of contents only
`--section <title>`	Show specific section by heading title or number

Examples:

knowns doc view "auth-pattern" --plain
knowns doc view "patterns/auth-pattern" --plain
knowns doc view "README" --info --plain      # Check size first
knowns doc view "README" --toc --plain       # Get TOC
knowns doc view "README" --section "2" --plain  # Read section

`knowns doc edit`

Edit a document.

knowns doc edit <name-or-path> [options]

Option	Description
`-t, --title`	New title
`--tags`	New tags
`-c, --content`	Replace content (or section content if `--section` used)
`-a, --append`	Append to content
`--section <title>`	Target section to replace (use with `-c`)
`--content-file <path>`	Replace content with file contents
`--append-file <path>`	Append file contents to document

Examples:

# Edit content directly
knowns doc edit "README" -c "New content here"
 
# Append content
knowns doc edit "README" -a "## New Section"
 
# Edit specific section only (context-efficient!)
knowns doc edit "README" --section "2. Installation" -c "New section content"
knowns doc edit "README" --section "2" -c "New content"  # By number
 
# Use file for long content (useful on Windows)
knowns doc edit "README" --content-file ./new-content.md
knowns doc edit "README" --append-file ./additional-section.md

`knowns doc validate`

Validate a documentation file format.

knowns doc validate <name> [options]

Option	Description
`--plain`	Plain text output (for AI)

`knowns doc repair`

Repair a corrupted documentation file.

knowns doc repair <name> [options]

Option	Description
`--plain`	Plain text output (for AI)

`knowns doc search-in`

Search text within a specific document.

knowns doc search-in <name> <query> [options]

Option	Description
`--plain`	Plain text output (for AI)
`-i, --ignore-case`	Case insensitive search

Examples:

knowns doc search-in "README" "authentication" --plain
knowns doc search-in "patterns/auth" "JWT" -i

`knowns doc replace`

Replace text in a document.

knowns doc replace <name> <old-text> <new-text> [options]

Option	Description
`--plain`	Plain text output (for AI)
`-a, --all`	Replace all occurrences (default: first only)

Examples:

# Replace first occurrence
knowns doc replace "README" "old-api" "new-api"
 
# Replace all occurrences
knowns doc replace "README" "v1" "v2" --all

`knowns doc replace-section`

Replace an entire section by its header.

knowns doc replace-section <name> <header> <content> [options]

Option	Description
`--plain`	Plain text output (for AI)

Examples:

knowns doc replace-section "README" "## Installation" $'Run the following:\n\n```bash\nnpm install knowns\n```'

Time Tracking Commands

`knowns time start`

Start tracking time on a task.

knowns time start <task-id>

`knowns time stop`

Stop the current timer.

knowns time stop

`knowns time pause` / `knowns time resume`

Pause or resume the current timer.

knowns time pause
knowns time resume

`knowns time status`

Show current timer status.

knowns time status

`knowns time add`

Add manual time entry.

knowns time add <task-id> <duration> [options]

Option	Description
`-n, --note`	Note for entry
`-d, --date`	Date (YYYY-MM-DD)

Examples:

knowns time add 42 2h -n "Code review"
knowns time add 42 30m -d "2025-01-15"

`knowns time report`

Generate time report.

knowns time report [options]

Option	Description
`--from`	Start date (YYYY-MM-DD)
`--to`	End date (YYYY-MM-DD)
`--by-label`	Group by label
`--csv`	CSV output

Search Commands

`knowns search`

Search tasks and documentation.

knowns search <query> [options]

Option	Description
`--type`	`task` or `doc`
`--status`	Filter tasks by status
`--priority`	Filter tasks by priority
`--plain`	Plain text output

Template Commands

`knowns template list`

List all available templates.

knowns template list [options]

Option	Description
`--plain`	Plain text output (for AI)

`knowns template view`

View template details and variables. Shorthand: knowns template <name>.

knowns template view <name> [options]
knowns template <name> [options]  # shorthand

Option	Description
`--plain`	Plain text output (for AI)

Examples:

knowns template view component --plain
knowns template component --plain  # shorthand

`knowns template run`

Run a template to generate code (interactive prompts for variables).

knowns template run <name> [options]

Option	Description
`--dry-run`	Preview output without writing files
`-f, --force`	Overwrite existing files
`--plain`	Plain text output (for AI)

Examples:

# Interactive mode (prompts for variables)
knowns template run component
 
# Preview generated code first
knowns template run component --dry-run
 
# Force overwrite existing files
knowns template run component --force

`knowns template create`

Create a new template scaffold.

knowns template create <name> [options]

Option	Description
`-d, --description <desc>`	Template description

Examples:

knowns template create api-endpoint -d "REST API endpoint generator"

Import Commands

Import docs and templates from external sources (Git, npm, or local).

`knowns import add`

Add a new import source. Shorthand: knowns import <source>.

knowns import add <source> [options]
knowns import <source> [options]  # shorthand

Source Format	Example
Git URL	`https://github.com/user/repo`
Git shorthand	`github:user/repo`, `gitlab:user/repo`
NPM package	`npm:package-name`
Local folder	`./path/to/folder`

Option	Description
`-n, --name <name>`	Custom name for the import
`-t, --type <type>`	Force source type: `git`, `npm`, `local`
`-r, --ref <ref>`	Git branch/tag or npm version
`--include <patterns...>`	Include patterns (e.g., `docs/*/.md`)
`--exclude <patterns...>`	Exclude patterns
`--link`	Symlink local imports (instead of copy)
`-f, --force`	Overwrite existing import
`--dry-run`	Preview without writing
`--plain`	Plain text output (for AI)

Examples:

# Import from GitHub
knowns import github:knowns-dev/templates
 
# Import specific branch with custom name
knowns import https://github.com/org/patterns --ref main --name patterns
 
# Import from npm with version
knowns import npm:@knowns/templates --ref ^1.0.0
 
# Import local folder with symlink
knowns import ./shared-docs --name shared --link
 
# Preview import
knowns import github:user/repo --dry-run

`knowns import list`

List all configured imports.

knowns import list [options]

Option	Description
`--plain`	Plain text output (for AI)

`knowns import sync`

Update imports from their sources.

knowns import sync [name] [options]

Option	Description
`-f, --force`	Overwrite locally modified files
`--dry-run`	Preview changes
`--plain`	Plain text output (for AI)

Examples:

# Sync all imports
knowns import sync
 
# Sync specific import
knowns import sync patterns
 
# Preview sync changes
knowns import sync --dry-run

`knowns import remove`

Remove an import configuration.

knowns import remove <name> [options]

Option	Description
`--delete`	Also delete imported files
`--plain`	Plain text output (for AI)

Import Structure

.knowns/
├── imports.json          # Import configurations
├── docs/
│   └── imports/
│       └── <name>/       # Imported docs
└── templates/
    └── <name>/           # Imported templates

Reference imported docs with @doc/imports/<name>/<path>

Other Commands

`knowns init`

Initialize Knowns in current directory with interactive wizard.

knowns init [project-name] [options]

Option	Description
`--wizard`	Force interactive wizard mode
`--no-wizard`	Skip wizard, use defaults
`-f, --force`	Reinitialize (overwrites existing config)

Examples:

# Interactive wizard (default when no name provided)
knowns init
 
# Quick init with name
knowns init my-project
 
# Force reinitialize
knowns init --force

Wizard prompts:

Project name
Default assignee
Default priority
Default labels
Time format (12h/24h)
AI guidelines version (CLI/MCP)
AI agent files to sync (CLAUDE.md, GEMINI.md, etc.)

`knowns config`

Manage project configuration.

knowns config <command> [key] [value]

Commands:

# Get a config value
knowns config get defaultAssignee --plain
 
# Set a config value
knowns config set defaultAssignee "@john"
 
# List all config
knowns config list

`knowns browser`

Open Web UI in browser.

knowns browser [options]

Option	Description
`-p, --port`	Custom port (default: 6420)
`--no-open`	Don't open browser

`knowns mcp`

Start MCP server for Claude Desktop integration.

knowns mcp [options]

Option	Description
`--info`	Show configuration instructions
`--verbose`	Enable verbose logging

Examples:

# Show setup instructions
knowns mcp --info
 
# Start server with logging
knowns mcp --verbose
 
# Auto-setup Claude Code + project .mcp.json
knowns mcp setup
knowns mcp setup --project   # only create .mcp.json in project
knowns mcp setup --global    # only register in Claude Code CLI

`knowns agents`

Manage AI agent instruction files. Syncs Knowns guidelines to various AI assistant configuration files.

knowns agents [options]

Option	Description
(none)	Interactive mode - select guidelines type/variant and files
`--update-instructions`	Non-interactive update
`--type <type>`	Guidelines type: `cli` or `mcp` (default: cli)
`--files <files>`	Comma-separated list of files to update

Supported files:

File	Description	Default
`CLAUDE.md`	Claude Code instructions	Yes
`AGENTS.md`	Agent SDK	Yes
`GEMINI.md`	Google Gemini
`.github/copilot-instructions.md`	GitHub Copilot

Examples:

# Interactive mode - select type and variant
knowns agents
 
# Non-interactive update (uses defaults)
knowns agents --update-instructions
 
# Update specific files with MCP version
knowns agents --update-instructions --type mcp --files "CLAUDE.md,AGENTS.md"

`knowns agents sync`

Quick sync of agent instruction files with latest guidelines.

knowns agents sync [options]

Option	Description
`--type <type>`	Guidelines type: `cli` or `mcp` (default: cli)
`--minimal`	Use minimal instruction only (default: full embedded guidelines)
`--all`	Update all instruction files (including Gemini, Copilot)

Template variants:

Variant	Size	Description
general (default)	~26KB	Full modular guidelines embedded in file
instruction (`--minimal`)	~1KB	Minimal - tells AI to call `knowns agents guideline`

Examples:

# Sync default files (CLAUDE.md, AGENTS.md) with full guidelines
knowns agents sync
 
# Sync all files
knowns agents sync --all
 
# Sync with minimal instruction only
knowns agents sync --minimal
 
# Sync with MCP guidelines
knowns agents sync --type mcp

`knowns agents guideline`

Output modular guidelines to stdout. AI agents should call this at session start.

knowns agents guideline [options]

Option	Description
(none)	Output full guidelines (all sections)
`--full`	Output full guidelines (all sections)
`--compact`	Output compact guidelines (core rules + common mistakes)
`--stage <stage>`	Output guidelines for specific stage: `creation`, `execution`, `completion`
`--core`	Output core rules only
`--commands`	Output commands reference only
`--mistakes`	Output common mistakes only
`--cli`	(Legacy) Same as default
`--mcp`	(Legacy) Same as default

Guidelines Structure (Modular):

Section	Description
Core Rules	Golden rules, must-follow principles
Commands Reference	CLI/MCP commands quick reference
Workflow Creation	Task creation workflow
Workflow Execution	Task execution workflow
Workflow Completion	Task completion workflow
Common Mistakes	Anti-patterns and DO vs DON'T

Examples:

# Full guidelines (default)
knowns agents guideline
 
# Compact for quick reference
knowns agents guideline --compact
 
# Stage-specific guidelines
knowns agents guideline --stage creation    # When creating tasks
knowns agents guideline --stage execution   # When implementing
knowns agents guideline --stage completion  # When finishing
 
# Individual sections
knowns agents guideline --core       # Core rules only
knowns agents guideline --commands   # Commands reference
knowns agents guideline --mistakes   # Common mistakes

Output Formats

`--plain`

Plain text output optimized for AI consumption. Always use this when working with AI assistants.

knowns task 42 --plain
knowns doc list --plain
knowns search "auth" --plain

Multi-line Input

Bash / Zsh

knowns task edit 42 --plan $'1. Step one\n2. Step two\n3. Step three'

PowerShell

knowns task edit 42 --notes "Line 1`nLine 2`nLine 3"

Heredoc (long content)

knowns task edit 42 --plan "$(cat <<EOF
1. Research existing patterns
2. Design solution
3. Implement
4. Write tests
5. Update documentation
EOF
)"

CLI Reference

Command Reference

Task Commands

knowns task <id> (Shorthand)

knowns task create

knowns task list

knowns task view

knowns task validate

knowns task repair

knowns task edit

Documentation Commands

knowns doc <path> (Shorthand)

knowns doc create

knowns doc list

knowns doc view

knowns doc edit

knowns doc validate

knowns doc repair

knowns doc search-in

knowns doc replace

knowns doc replace-section

Time Tracking Commands

knowns time start

knowns time stop

knowns time pause / knowns time resume

knowns time status

knowns time add

knowns time report

Search Commands

knowns search

Template Commands

knowns template list

knowns template view

knowns template run

knowns template create

Import Commands

knowns import add

knowns import list

knowns import sync

knowns import remove

Import Structure

Other Commands

knowns init

knowns config

knowns browser

knowns mcp

knowns agents

knowns agents sync

knowns agents guideline

Output Formats

--plain

Multi-line Input

Bash / Zsh

PowerShell

Heredoc (long content)

`knowns task <id>` (Shorthand)

`knowns task create`

`knowns task list`

`knowns task view`

`knowns task validate`

`knowns task repair`

`knowns task edit`

`knowns doc <path>` (Shorthand)

`knowns doc create`

`knowns doc list`

`knowns doc view`

`knowns doc edit`

`knowns doc validate`

`knowns doc repair`

`knowns doc search-in`

`knowns doc replace`

`knowns doc replace-section`

`knowns time start`

`knowns time stop`

`knowns time pause` / `knowns time resume`

`knowns time status`

`knowns time add`

`knowns time report`

`knowns search`

`knowns template list`

`knowns template view`

`knowns template run`

`knowns template create`

`knowns import add`

`knowns import list`

`knowns import sync`

`knowns import remove`

`knowns init`

`knowns config`

`knowns browser`

`knowns mcp`

`knowns agents`

`knowns agents sync`

`knowns agents guideline`

`--plain`