Scan where the code lives.

The CLI reads your repositories on a laptop or in CI, finds the routes, calls, queues and models, and uploads only the resulting graph to your workspace. It is the same scanner our hosted runner uses, so both land identically. On a pull request it tells you what the change breaks.

$ npm install -g kuuhaku
$ kuuhaku login --token <token from the app>
$ kuuhaku scan ~/work/company --push
$ kuuhaku check ~/work/company

Install

npm is the way to go: one command on every system with Node 18 or newer, and updates with npm update -g.

npm install -g kuuhaku

npx kuuhaku scan . --push

kuuhaku.exe scan C:\work --push

docker run --rm -v "$PWD:/code:ro" \
  -e KUUHAKU_TOKEN kuuhaku/cli \
  scan /code --push

brew install kuuhaku
scoop install kuuhaku

Connect a machine

1. Get the workspace's push token.

   In the app, on the CLI page or in Settings, Scanning. The token can only upload graphs to that workspace; it is shown once.

2. Log in from the terminal.

   Once per machine. The token is kept in ~/.kuuhaku, readable by your user only.

   $ kuuhaku login --token <token> --api https://api.your-domain

3. Scan and push.

   Point it at a folder of repositories, or at an architecture.yaml. The machine appears on the workspace's CLI page with its system, version and last push.

   $ kuuhaku scan ~/work/company --push

Commands

In CI

Scan on every push to main. Save the token as the repository secret KUUHAKU_TOKEN; the job appears as one machine, named after the repository.

name: Kuuhaku
on:
  push:
    branches: [main]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 400
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npx kuuhaku scan . --push --api https://api.your-domain
        env:
          KUUHAKU_TOKEN: ${{ secrets.KUUHAKU_TOKEN }}

Check every pull request. The job fails when the change breaks a caller, and the report goes on the pull request as a comment that the next run updates. Nothing is pushed, so no token is needed.

name: Kuuhaku check
on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npx kuuhaku check . --base origin/${{ github.base_ref }} --markdown check.md
      - if: always() && hashFiles('check.md') != ''
        run: gh pr comment ${{ github.event.pull_request.number }} --edit-last --body-file check.md || gh pr comment ${{ github.event.pull_request.number }} --body-file check.md
        env:
          GH_TOKEN: ${{ github.token }}

On Bitbucket Pipelines, fetch the destination branch first, since a pipeline clones only its own: git fetch origin "+refs/heads/$BITBUCKET_PR_DESTINATION_BRANCH:refs/remotes/origin/$BITBUCKET_PR_DESTINATION_BRANCH", then npx kuuhaku check . --base origin/$BITBUCKET_PR_DESTINATION_BRANCH. A workspace of several repositories needs the others checked out beside the changed one; they are only read.

What leaves the machine

graph.json and nothing else. You can open it before pushing: kuuhaku scan without --push writes it and stops.