Installation

Get Knowns CLI up and running on your system.

Use this page when you are installing Knowns for the first time, pinning a version, or choosing the right install method for your environment.

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.18.3 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.18.3"
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 the v0.18 series onward, the browser flow also covers workspace switching, code graph exploration, richer chat UX, and optional watcher-based code refresh flows.

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.

Related

• Introduction - Product overview and quick start
• MCP Integration - Connect Knowns to AI assistants
• CLI Reference - Full command reference