# Installation

How to install and configure Knowns CLI on your system

## [Prerequisites](https://knowns.sh/docs/installation#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](https://knowns.sh/docs/installation#check-your-version)

```
node --version
```

### [Platform-specific installation](https://knowns.sh/docs/installation#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](https://knowns.sh/docs/installation#additional-requirements)

- **Git** \- Knowns requires a git repository for version control

## [Choose An Install Method](https://knowns.sh/docs/installation#choose-an-install-method)

| Method | Best For | Notes |
| --- | --- | --- |
| Shell script | macOS and Linux users who want the official binary | Supports version pinning and script-managed updates |
| PowerShell | Windows users who want the official binary | Supports version pinning and script-managed updates |
| Homebrew | macOS and Linux users already using Homebrew | Upgrade with `brew upgrade knowns-dev/tap/knowns` |
| npm | Users already working in a Node.js toolchain | Requires Node.js 20+ |
| npx | One-off usage without a global install | Slower than a normal install |

## [Install Methods](https://knowns.sh/docs/installation#install-methods)

### [Shell](https://knowns.sh/docs/installation#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](https://knowns.sh/docs/installation#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](https://knowns.sh/docs/installation#homebrew)

```
brew install knowns-dev/tap/knowns
```

### [npm](https://knowns.sh/docs/installation#npm)

```
npm install -g knowns
```

### [npx](https://knowns.sh/docs/installation#npx)

```
npx knowns
```

## [Verify Installation](https://knowns.sh/docs/installation#verify-installation)

After installation, verify that Knowns is available:

```
knowns --version
```

You should see the version number printed.

## [Initialize a Project](https://knowns.sh/docs/installation#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](https://knowns.sh/docs/installation#configuration)

The `config.json` file contains project settings:

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

## [Browser UI](https://knowns.sh/docs/installation#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)](https://knowns.sh/docs/installation#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](https://knowns.sh/docs/installation#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](https://knowns.sh/docs/installation#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](https://knowns.sh/docs/installation#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.