Installation

Get Knowns CLI up and running 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

Install Methods

Shell

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

PowerShell

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

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

If you prefer reinstalling from the bootstrap script:

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

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.