Installation

Get Knowns CLI up and running on your system.

Prerequisites

Before installing Knowns, make sure you have one of the following installed:

Check your version

# For Node.js
node --version
 
# For Bun
bun --version

Platform-specific installation

macOS:

# Using Homebrew
brew install node
# or
brew install oven-sh/bun/bun

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
 
# or Bun
curl -fsSL https://bun.sh/install | bash

Windows:

# Using winget
winget install OpenJS.NodeJS
# or
winget install Oven-sh.Bun

Additional requirements

• Git - Knowns requires a git repository for version control

Package Managers

npm

npm install -g knowns

yarn

yarn global add knowns

pnpm

pnpm add -g knowns

bun

bun install -g knowns

Verify Installation

After installation, verify that Knowns is available:

knowns --version  # expect 0.8.x (latest)

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

This opens a local server with:

• Kanban board view
• Document browser
• 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:

npm install -g knowns@latest

Uninstalling

To remove Knowns:

npm uninstall -g knowns

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