Kompass CLI

The Kompass skill lets an AI assistant that runs on your own computer, such as Claude Code, look things up and make changes in Kompass for you. Ask it "which projects for Acme are still at the quote stage?" or "mark task 512 as complete" and it works it out using the Kompass command-line tool, acting as you and with your permissions.

You need two downloads: the Kompass command-line tool for your computer, and the skill file that teaches your assistant how to use it. Setup takes about ten minutes.

Downloads

Latest version: 26.9.54 (29 September 2026). To see which version you have installed, run kompass version.

Not sure which Mac you have? Open the Apple menu and choose About This Mac. If it lists a Chip starting with "Apple", use Apple silicon; if it lists an Intel Processor, use Intel.

Step 1: Create a personal access token

The tool signs in to Kompass with a personal access token rather than your password.

1. In Kompass, open Settings from your user menu and go to the API tokens tab.
2. Click Create token and give it a name you will recognise, such as Claude on my laptop.
3. Choose the access:
   • Read only, if you just want the assistant to answer questions. This is the safest place to start.
   • Read and Write, if you want it to make changes too.
4. Click Create and copy the token. It is shown only once.

More detail: Personal access tokens (PATs).

Step 2: Install the command-line tool

Windows

1. Download the Windows zip from the table above, right-click it and choose Extract All.
2. Create the folder C:\Users\<your name>\AppData\Local\Programs\Kompass  and move kompass.exe  into it.
3. Open the Start menu, search for Edit environment variables for your account and open it.
4. Select Path, click Edit, then New, paste the folder path from step 2 and click OK twice.
5. Open a new PowerShell or Terminal window and run kompass --help . You should see a list of commands.

If Windows shows "Windows protected your PC" the first time, click More info and then Run anyway.

Mac

1. Download the Mac zip for your processor and double-click it in Finder to extract kompass .
2. Open Terminal and run these commands (enter your Mac password when asked):

sudo mkdir -p /usr/local/bin
sudo mv ~/Downloads/kompass /usr/local/bin/
sudo xattr -d com.apple.quarantine /usr/local/bin/kompass

3. Run kompass --help . You should see a list of commands.

The last command stops macOS blocking the tool as "from an unidentified developer". If it reports "No such xattr", that is fine.

Linux

unzip kompass-cli-26.9.54-linux-amd64.zip
sudo install kompass /usr/local/bin/
kompass --help

Step 3: Sign in

In a terminal, tell the tool where your Kompass is (the address you open in your browser), then sign in and paste the token from step 1 when asked:

kompass config set base_url https://yourcompany.kompassbms.com
kompass auth login

Check it worked:

kompass auth whoami --pretty

You should see your name and email. The token is saved in the tool's settings file on your computer (run kompass config path  to see where), so you only do this once per computer.

Step 4: Add the skill to your assistant

Claude Code

Extract kompass-skill-26.9.54.zip  into your Claude skills folder, so that you end up with a kompass  folder containing SKILL.md :

• Mac and Linux: ~/.claude/skills/kompass/SKILL.md

mkdir -p ~/.claude/skills
unzip ~/Downloads/kompass-skill-26.9.54.zip -d ~/.claude/skills

• Windows: C:\Users\<your name>\.claude\skills\kompass\SKILL.md

Start a new Claude Code session and type /kompass , or simply ask a question about your Kompass data.

Other assistants

Any assistant that supports skills (a folder with a SKILL.md  file) can use the same file. Put the kompass  folder wherever that assistant loads skills from; check its documentation for the location. The assistant must be able to run commands on your computer.

Try it

Some things to ask:

• "Who am I signed in to Kompass as?"
• "List the open projects for Acme and their phases."
• "Which tasks are assigned to me this week?"
• "Summarise the diary entries on project 1042."
• "Move project 1042 to accepted." (needs a token with Write access)

How changes are kept safe

• The assistant can only do what your Kompass account and token allow. With a Read-only token it cannot change anything.
• Every change is previewed first. The skill tells the assistant to show you exactly what it is about to send and wait for you to agree before it goes ahead.
• Changes are recorded in Kompass history under your name, exactly as if you had made them yourself.
• To cut off access, delete the token on the API tokens tab. It stops working immediately.

Using the tool yourself

You can also run the tool directly, or from your own scripts. Every command has built-in help:

kompass --help
kompass projects list --help
kompass clients list --filter search=acme --output table

Output is JSON by default; add --output table  for a readable table. Any command that changes data needs --dry-run  (preview only) or --confirm  (send it). For automated scripts, set the KOMPASS_TOKEN  and KOMPASS_BASE_URL  environment variables instead of running kompass auth login .

Updating

When this article lists a newer version, download the zip for your computer again and replace the kompass  file (or kompass.exe ) with the new one, and replace the skill folder with the one in the new skill zip. Your sign-in is kept.

Troubleshooting

• "kompass: command not found" or "not recognised": the tool is not on your Path. On Windows, check step 2 and open a new terminal window afterwards. On Mac and Linux, check that /usr/local/bin/kompass  exists.
• "no base URL configured": run the kompass config set base_url  command from step 3.
• "not authenticated" or error 401: the token is missing, expired or deleted. Create a new one and run kompass auth login  again.
• Error 403: your account or token is not allowed to do that, for example a change made with a Read-only token. Ask your Kompass administrator if you think you should have access.
• The assistant does not seem to use the skill: check that the file is at .claude/skills/kompass/SKILL.md  (not inside an extra folder), then start a new session.