Installation

How to install and configure Knowns CLI on your system

Prerequisites

Knowns supports multiple install paths:

• Shell script via https://knowns.sh/script/install
• PowerShell via https://knowns.sh/script/install.ps1
• Homebrew via brew install knowns-dev/tap/knowns
• npm via npm install -g knowns
• npx knowns for no global install

Only the npm-based path requires Node.js 20+.

Check your version

node --version

Platform-specific installation

macOS:

# If using npm-based install
brew install node

Linux (Ubuntu/Debian):

# Node.js via NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Windows:

# Using winget
winget install OpenJS.NodeJS

Additional requirements

• Git - Knowns requires a git repository for version control

Choose An Install Method

Install Methods

Shell

curl -fsSL https://knowns.sh/script/install | sh

Pin a specific version:

KNOWNS_VERSION=v0.20.1 curl -fsSL https://knowns.sh/script/install | sh

PowerShell

irm https://knowns.sh/script/install.ps1 | iex

Pin a specific version:

$env:KNOWNS_VERSION = "v0.20.1"
irm https://knowns.sh/script/install.ps1 | iex

Homebrew

brew install knowns-dev/tap/knowns

npm

npm install -g knowns

npx

npx knowns

Verify Installation

After installation, verify that Knowns is available:

knowns --version

You should see the version number printed.

Initialize a Project

Navigate to your project directory and run:

cd your-project
knowns init

Note: Knowns requires a git repository. If your project is not yet a git repo, initialize it first:

git init
knowns init

Running knowns init starts an interactive wizard:

🚀 Knowns Project Setup Wizard
   Configure your project settings

? Project name: my-project
? Git tracking mode: Git Tracked (recommended for teams)
? AI Guidelines type: CLI
? Select AI agent files to create/update:
  ◉ CLAUDE.md (Claude Code)
  ◉ AGENTS.md (Agent SDK)
  ◯ GEMINI.md (Google Gemini)
  ◯ .github/copilot-instructions.md (GitHub Copilot)

This creates a .knowns/ folder with the following structure:

.knowns/
├── config.json # Project configuration
├── tasks/ # Task files
└── docs/ # Documentation files

Configuration

The config.json file contains project settings:

{
  "name": "your-project",
  "version": "1.0.0",
  "settings": {
    "defaultPriority": "medium",
    "taskPrefix": "TASK"
  }
}

Browser UI

Knowns includes a web-based UI for visual task management:

knowns browser --open

This opens a local server with:

• Kanban board view
• Document browser
• Memory browser
• Knowledge graph
• Task details panel
• Dark mode support

From v0.18 onward, the browser flow covers workspace switching, code graph exploration, richer chat UX, and optional watcher-based code refresh flows. The v0.20 series adds native ONNX embedding, consolidated MCP tools, AI permission guards, and structural knowledge retrieval.

Claude Code MCP Setup (Optional)

Set up Model Context Protocol for Claude Code in one step:

knowns mcp setup

• Creates .mcp.json for project-level auto-discovery
• Registers the Knowns MCP server with claude mcp add-json when the Claude CLI is installed

Updating

To update Knowns to the latest version:

knowns update

Upgrade guidance depends on how you installed Knowns:

• Shell or PowerShell install: knowns update can use install metadata for direct self-update
• Homebrew: brew upgrade knowns-dev/tap/knowns
• npm or manual install: prefer your original install path/tooling

If you prefer reinstalling from the bootstrap script:

curl -fsSL https://knowns.sh/script/install | sh

Next Steps

After installation:

1. Run knowns init in your repository
2. Open the local UI with knowns browser --open
3. Set up AI integration with knowns mcp setup if needed

Uninstalling

To remove Knowns:

curl -fsSL https://knowns.sh/script/uninstall | sh

On Windows PowerShell:

irm https://knowns.sh/script/uninstall.ps1 | iex

Note: This does not remove .knowns/ folders from your projects.