CLI Reference
Complete command reference for Knowns CLI
Command Reference
Complete reference for all Knowns CLI commands.
Conventions
- Use
--plainwhen an AI or script needs text output that is easy to parse. - Use
--jsonwhen you want structured output. - Use
knowns syncwhen you want generated files and platform artifacts to match the current config.
Initialize and Setup
knowns init
Initializes Knowns in the current project.
bash
knowns init
knowns init my-project --no-wizard
knowns init --force
What init configures:
- project name
- git tracking mode (with per-section toggles)
- semantic search
- embedding model
| Option | Description |
|---|---|
--wizard | Force interactive wizard mode |
--no-wizard | Skip wizard, use defaults |
-f, --force | Reinitialize (overwrites existing config) |
knowns setup
Configures AI tool integrations for an initialized project.
bash
knowns setup # Interactive platform selector
knowns setup claude # Claude Code: CLAUDE.md, .mcp.json, skills, hooks
knowns setup opencode # OpenCode: OPENCODE.md, opencode.json, skills, hooks
knowns setup kiro # Kiro: .kiro steering/settings, skills, hooks
knowns setup copilot # GitHub Copilot: .github/copilot-instructions.md
knowns setup all # All supported platforms
knowns sync
Re-applies .knowns/config.json to the current machine.
bash
knowns sync
knowns sync --skills
knowns sync --instructions
knowns sync --model
knowns sync --instructions --platform claude
knowns sync --instructions --platform cursor
| Option | Description |
|---|---|
--skills | Sync skills only |
--instructions | Sync instruction files only |
--model | Download embedding model only |
--platform | Sync specific platform (claude, opencode, kiro, codex, cursor, copilot, agents) |
knowns update
Updates the CLI and syncs project artifacts afterward.
bash
knowns update
knowns update --check
Task Commands
knowns task <id> (Shorthand)
View a single task (shorthand for knowns task view).
bash
knowns task <id> [options]
| Option | Description |
|---|---|
--plain | Plain text output (for AI) |
Examples:
bash
knowns task 42 --plain
knowns task create
Create a new task.
bash
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 |
--spec | Link to spec document (e.g., specs/user-auth) |
--fulfills | Spec ACs this task fulfills (e.g., AC-1,AC-2) |
Examples:
bash
# 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
# SDD task linked to spec
knowns task create "Implement search API" \
--spec specs/semantic-search \
--fulfills AC-1,AC-2
knowns task list
List all tasks.
bash
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:
bash
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).
bash
knowns task view <id> [options]
| Option | Description |
|---|---|
--plain | Plain text output (for AI) |
knowns task edit
Edit an existing task.
bash
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:
bash
# 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"
knowns task validate
Validate a task file format.
bash
knowns task validate <id> [options]
knowns task repair
Repair a corrupted task file.
bash
knowns task repair <id> [options]
Documentation Commands
knowns doc <path> (Shorthand)
View a document (shorthand for knowns doc view).
bash
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:
bash
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.
bash
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:
bash
# 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.
bash
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) |
knowns doc edit
Edit a document.
bash
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:
bash
# 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 search-in
Search text within a specific document.
bash
knowns doc search-in <name> <query> [options]
| Option | Description |
|---|---|
--plain | Plain text output (for AI) |
-i, --ignore-case | Case insensitive search |
knowns doc replace
Replace text in a document.
bash
knowns doc replace <name> <old-text> <new-text> [options]
| Option | Description |
|---|---|
-a, --all | Replace all occurrences (default: first only) |
knowns doc replace-section
Replace an entire section by its header.
bash
knowns doc replace-section <name> <header> <content>
Time Tracking Commands
knowns time start
Start tracking time on a task.
bash
knowns time start <task-id>
knowns time stop
Stop the current timer.
bash
knowns time stop
knowns time pause / knowns time resume
Pause or resume the current timer.
bash
knowns time pause
knowns time resume
knowns time status
Show current timer status.
bash
knowns time status
knowns time add
Add manual time entry.
bash
knowns time add <task-id> <duration> [options]
| Option | Description |
|---|---|
-n, --note | Note for entry |
-d, --date | Date (YYYY-MM-DD) |
Examples:
bash
knowns time add 42 2h -n "Code review"
knowns time add 42 30m -d "2025-01-15"
knowns time report
Generate time report.
bash
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, docs, and memory entries.
bash
knowns search <query> [options]
| Option | Description |
|---|---|
--type | task, doc, or memory |
--status | Filter tasks by status |
--priority | Filter tasks by priority |
--keyword | Keyword-only mode |
--plain | Plain text output |
bash
knowns search --status-check # Check search readiness
knowns search --reindex # Rebuild index
knowns retrieve
Build a structured context pack from docs, tasks, and memories.
bash
knowns retrieve "query" --json
knowns retrieve "auth flow" --source-types doc,task --json
knowns resolve
Resolve a semantic reference and traverse related entities.
bash
knowns resolve <semantic-ref> [flags]
| Option | Description |
|---|---|
--depth | Max traversal hops, 1-3 (default 1) |
--direction | Traversal direction: outbound (default), inbound, or both |
--relation | Filter by relation kinds (comma-separated) |
--type | Filter result entities by kind (comma-separated) |
Code Intelligence
LSP Management
bash
knowns lsp list # Show supported languages and their status
knowns lsp install <language> # Download and install an LSP server
knowns lsp cleanup # Remove old LSP server versions
Knowns auto-detects project languages and checks for LSP binaries. If a binary is missing, knowns lsp list shows install guidance.
Code Operations (via MCP)
Code intelligence is LSP-based and accessed through the MCP code tool:
symbols— list symbols in a filefind— search symbols by name pattern with optional body/depthdefinition— go to definitionreferences— find all referencesimplementations— find implementations of interfacediagnostics— get compile errors/warningsrename— rename symbol across workspacereplace— regex/literal text replacementreplace_body— replace entire symbol bodyinsert— insert code before/after a symboldelete— safe delete with reference check
Template Commands
knowns template list
List all available templates.
bash
knowns template list [options]
knowns template view
View template details and variables. Shorthand: knowns template <name>.
bash
knowns template view <name> [options]
knowns template <name> [options] # shorthand
knowns template run
Run a template to generate code (interactive prompts for variables).
bash
knowns template run <name> [options]
| Option | Description |
|---|---|
--dry-run | Preview output without writing files |
-f, --force | Overwrite existing files |
knowns template create
Create a new template scaffold.
bash
knowns template create <name> [options]
| Option | Description |
|---|---|
-d, --description <desc> | Template description |
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>.
bash
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 |
knowns import list
List all configured imports.
bash
knowns import list [options]
knowns import sync
Update imports from their sources.
bash
knowns import sync [name] [options]
| Option | Description |
|---|---|
-f, --force | Overwrite locally modified files |
--dry-run | Preview changes |
knowns import remove
Remove an import configuration.
bash
knowns import remove <name> [options]
| Option | Description |
|---|---|
--delete | Also delete imported files |
Memory Commands
Persistent memory lets AI keep reusable patterns, decisions, and conventions across sessions.
knowns memory list
bash
knowns memory list [options]
| Option | Description |
|---|---|
--layer | Filter by project or global |
--category | Filter by category |
--tag | Filter by tag |
--plain | Plain text output (for AI) |
knowns memory view
bash
knowns memory view <id> [options]
knowns memory add
bash
knowns memory add [options]
| Option | Description |
|---|---|
-t, --title | Memory title |
-c, --content | Memory content |
--layer | project (default) or global |
--category | Category such as pattern or decision |
--tags | Comma-separated tags |
knowns memory promote / knowns memory demote
bash
knowns memory promote <id>
knowns memory demote <id>
Other Commands
knowns config
Manage project configuration.
bash
# Interactive feature toggle UI
knowns config toggle
# Get a config value
knowns config get defaultAssignee --plain
# Set a config value
knowns config set defaultAssignee "@john"
# Set feature toggles
knowns config set embedding true
knowns config set lsp true
knowns config set enableChatUI true
knowns config set gitTracking.tasks true
knowns config set gitTracking.memories false
# List all config
knowns config list
knowns browser
Launch the local Web UI and AI Chat.
bash
knowns browser [flags]
| Option | Description |
|---|---|
--dev | Enable development mode (verbose logging) |
--open | Open browser after starting |
--no-open | Don't automatically open browser |
--port | HTTP server port (default: 6420; tries next ports if busy) |
--project | Project path to open directly |
--restart | Restart server if already running |
--scan | Comma-separated directories to scan for projects |
--tunnel | Expose via a Cloudflare Quick Tunnel (requires cloudflared) |
--watch | Enable file watcher for auto-indexing on code changes |
knowns tunnel
Manage Cloudflare Quick Tunnels for the local server.
bash
knowns tunnel status [--port <port>]
knowns tunnel stop [--port <port>]
knowns validate
Run validation checks.
bash
knowns validate --plain
knowns validate --scope docs --plain
knowns validate --scope sdd --plain
knowns validate --strict --plain
knowns audit
Inspect the MCP tool call audit trail.
bash
knowns audit recent [--limit 50] [--tool <name>] [--result success|error|denied]
knowns audit stats [--project <path>] [--tool <name>]
knowns status
Show project readiness summary.
bash
knowns status
knowns board
Show the Kanban board in the terminal.
bash
knowns board
knowns model
Manage embedding models.
bash
knowns model list
knowns model download multilingual-e5-small
knowns model set multilingual-e5-small
knowns model status
knowns mcp
Start the MCP server.
bash
knowns mcp --stdio
knowns mcp setup
knowns runtime
Manage runtime adapters.
bash
knowns runtime install <runtime>
knowns runtime uninstall <runtime>
knowns runtime status
knowns guidelines
Display Knowns usage guidelines for AI agents.
bash
knowns guidelines --plain
knowns guidelines --compact
knowns guidelines --search "time tracking"
knowns guidelines --mode mcp --plain
knowns agents guideline
Output modular guidelines to stdout. AI agents call this at session start.
bash
knowns agents guideline
knowns agents guideline --compact
knowns agents guideline --stage creation
knowns agents guideline --stage execution
knowns agents guideline --stage completion
knowns agents guideline --core
knowns agents guideline --commands
Output Formats
--plain
Plain text output optimized for AI consumption. Always use this when working with AI assistants.
bash
knowns task 42 --plain
knowns doc list --plain
knowns search "auth" --plain
Multi-line Input
Bash / Zsh
bash
knowns task edit 42 --plan $'1. Step one\n2. Step two\n3. Step three'
PowerShell
PowerShell
knowns task edit 42 --notes "Line 1`nLine 2`nLine 3"
Heredoc (long content)
bash
knowns task edit 42 --plan "$(cat <<EOF
1. Research existing patterns
2. Design solution
3. Implement
4. Write tests
5. Update documentation
EOF
)"
Lệnh
Dùng knowns <command> --help để xem syntax chính xác. Trang này là tổng quan thực dụng.
Conventions
--plainkhi AI hoặc script cần text output dễ parse--jsonkhi cần structured outputknowns synckhi muốn generated files khớp lại với config
Init và Setup
knowns init
Khởi tạo Knowns trong project hiện tại.
bash
knowns init
knowns init my-project --no-wizard
knowns init --force
Init cấu hình:
- tên project
- git tracking mode (với per-section toggles)
- semantic search
- embedding model
knowns setup
Cấu hình AI tool integrations cho project đã init.
bash
knowns setup # Interactive platform selector
knowns setup claude # Claude Code: CLAUDE.md, .mcp.json, skills, hooks
knowns setup opencode # OpenCode: OPENCODE.md, opencode.json, skills, hooks
knowns setup kiro # Kiro: .kiro steering/settings, skills, hooks
knowns setup copilot # GitHub Copilot: .github/copilot-instructions.md
knowns setup all # Tất cả platforms
knowns sync
Re-apply .knowns/config.json lên máy hiện tại.
bash
knowns sync
knowns sync --skills
knowns sync --instructions
knowns sync --model
knowns sync --instructions --platform claude
knowns sync --instructions --platform cursor
knowns update
Cập nhật CLI và sync artifacts sau đó.
bash
knowns update
knowns update --check
Task
bash
knowns task create "Title" -d "Description"
knowns task create "Add auth" \
--ac "User can login" \
--ac "JWT token returned" \
--priority high \
-l auth
knowns task list --plain
knowns task list --status in-progress --assignee @me
knowns task <id> --plain
knowns task edit <id> -s in-progress
knowns task edit <id> --check-ac 1
knowns task edit <id> --append-notes "Completed middleware"
knowns task edit <id> --plan $'1. Research\n2. Implement\n3. Test'
Doc
bash
knowns doc create "Architecture" -d "System overview" -f architecture
knowns doc create "Auth Pattern" -d "JWT auth pattern" -f patterns -t auth -t security
knowns doc list --plain
knowns doc "architecture/auth" --plain
knowns doc "architecture/auth" --plain --smart
knowns doc "architecture/auth" --info --plain
knowns doc "architecture/auth" --toc --plain
knowns doc "architecture/auth" --section "2" --plain
knowns doc edit "architecture/auth" -a "\n\n## Notes\n..."
knowns doc edit "architecture/auth" -c "# New content"
knowns doc edit "architecture/auth" --section "2" -c "## 2. Updated section"
Search, retrieve, resolve
bash
knowns search "authentication" --plain
knowns search "jwt" --type doc --plain
knowns search "jwt" --keyword --plain
knowns search --status-check
knowns search --reindex
knowns retrieve "how auth works" --json
knowns retrieve "auth flow" --source-types doc,task --json
knowns resolve "@doc/specs/auth{implements}" --plain
knowns resolve "@doc/specs/auth{depends}" --direction inbound --depth 2 --plain
Memory
bash
knowns memory add "We use repository pattern" --category decision
knowns memory list --plain
knowns memory <id> --plain
knowns memory edit <id> --append "More detail"
Templates
bash
knowns template list
knowns template get <name>
knowns template run <name>
knowns template create <name>
Code intelligence
LSP management
bash
knowns lsp list # Hiển thị languages và status
knowns lsp install <language> # Download và install LSP server
knowns lsp cleanup # Xóa LSP server versions cũ
Code operations (via MCP)
Code intelligence dựa trên LSP, truy cập qua MCP code tool:
symbols— list symbols trong filefind— search symbols theo name patterndefinition— go to definitionreferences— find all referencesimplementations— find implementationsdiagnostics— get compile errors/warningsrename— rename symbol across workspacereplace— regex/literal text replacementreplace_body— replace entire symbol bodyinsert— insert code before/after symboldelete— safe delete with reference check
Validation
bash
knowns validate --plain
knowns validate --scope docs --plain
knowns validate --scope sdd --plain
knowns validate --strict --plain
Time tracking
bash
knowns time start <task-id>
knowns time stop
knowns time add <task-id> 1h30m -n "Pair programming"
knowns time report
Browser UI
bash
knowns browser
knowns browser --open
knowns browser --port 6421
Config
bash
# Interactive feature toggle UI
knowns config toggle
# Get/set
knowns config get defaultAssignee --plain
knowns config set defaultAssignee "@john"
knowns config set embedding true
knowns config set lsp true
knowns config set enableChatUI true
knowns config set gitTracking.tasks true
knowns config set gitTracking.memories false
knowns config list
Model
bash
knowns model list
knowns model download multilingual-e5-small
knowns model set multilingual-e5-small
knowns model status
Import
bash
knowns import add <name> <source>
knowns import sync
knowns import list
Guidelines
bash
knowns guidelines --plain
knowns guidelines --compact
knowns agents guideline
knowns agents guideline --compact
knowns agents guideline --stage execution