The CLI

Projects and folders

One CLI can be connected to several projects at once, each on its own Enterprise Server. Every prompt, tool call and captured session goes only to the project the working folder belongs to — and a folder that belongs to none sends nothing anywhere.

One CLI, several projects

Say you work on Acme Platform at knwlge.acme.example and help out on Northwind Data at knwlge.northwind.example. Both are connected on your laptop, with one Knwlge login. Neither server learns about the other: each gets its own install id, and requests name only their own project.

Connect a project

knwlge init --api-url https://knwlge.northwind.example

A second project is added beside the first; it never replaces it. Signing in reads the project's repository list from its server, which is how folders are matched to it.

How a folder picks its project

1. A pinned folder uses the project it is pinned to, and so do the folders under it.
2. Otherwise the folder's repository — or, for a folder that is not a repository, the repositories directly under it — is matched against each project's list, by the repository's remote. The project with the most of them wins.
3. A tie is never guessed. Knwlge stays off in that folder until you pin it.
4. No match, no project. Knwlge stays off: the status line says ◇ knwlge no suitable project found, tools answer locally, and no server is contacted.

An agent's MCP server settles its folder's project once, when the agent session starts. After connecting or pinning, start a new agent session.

See what a folder uses

knwlge projects

$ knwlge projects
  ██   ▄█▀   Knwlge CLI v1.0.0
   █▄▄█▀     ● signed in as ada@acme.example · project Acme Platform
   █▀▀█▄     ~/.team-context-gateway · node v22.20.0 · darwin arm64  ·  Docs https://knwlge.com/docs
  ██   ▀█▄   Give your agent the context it's been missing.

───────────────────────────────────────────────────────────────────────────────

● Acme Platform   ◀ this folder
    server    knwlge.acme.example
    account   ada@acme.example
    4 repos   api  web  infra  billing  · listed 2 h ago

● Northwind Data
    server    knwlge.northwind.example
    account   ada@northwind.example
    2 repos   pipelines  warehouse  · listed 2 h ago
    pinned    ~/code/northwind

This folder  ~/code/acme  →  Acme Platform · api, web

which says why, for this folder or another (--dir):

$ knwlge projects which
~/code/acme/api
  →  Acme Platform   its repositories include api

$ knwlge projects which
~/code/scratch
  →  no project   none of these repositories is in a connected project, so knwlge stays off here

Add --json to any of these for the same report in a form scripts can read.

Pin a folder

knwlge projects pin --project "Northwind Data" --dir ~/code/northwind
knwlge projects unpin --dir ~/code/northwind     # match it by its repositories again

Pin a folder when its repositories are in two projects, or when it should use a project although its repositories are not listed there. A pin covers the folders under it too.

Refresh repository lists

Each project's repositories are read from its server when you sign in, when the sidecar starts and every six hours after. When an admin has just added a repository, read them now:

$ knwlge projects refresh
● Acme Platform    4 repositories
● Northwind Data   2 repositories

Leave a project

knwlge logout --project "Northwind Data"   # one project
knwlge logout --all                        # every one

Logging out revokes the session at Knwlge Global and forgets the saved credentials for that project. The other projects stay connected.

Folders with several checkouts

Working from a folder that holds several checkouts side by side — ~/code/acme with api, web and infra under it — is supported. Run your agent there and install the hooks once with --repo-root pointing at the folder. For each prompt, the sidecar sends the checkouts the request points at, primary first:

• the checkouts holding the files the request is about, the most files first;
• then the ones the prompt names by directory — compare api with web briefs both;
• when nothing points anywhere, every checkout there, up to eight.

The server authorizes each repository on its own, so this only widens a brief to repositories you can already read. When a brief spans several, each card names its repository and the brief opens with a short system map: the repositories, their purpose, and the HTTP routes one calls on another.