Installation & Setup

This document collects everything needed to get KK working on a developer machine: Git, the KK CLI (build or download), and the optional rclone binary used for cloud remotes.

Contents

Supported Platforms

Quick Checks

Verify these are available before proceeding:

git --version
go version
rclone version   # optional

Prerequisites

1) Install Git

Windows

Download and install from git-scm.com. Choose options that add Git to your PATH.

macOS

Install via Homebrew brew install git or from git-scm.com.

Linux

Use your distro package manager, e.g. sudo apt install git.

Verify

git --version

2) Install Go (required to build KK)

Download from go.dev/dl/ and install a Go version >= 1.23 as declared in go.mod.

Verify

go version

3) Optional: Install rclone (for rclone-backed remotes)

rclone is optional if you only use local/NAS remotes or native Google Drive via kk setup gdrive. If you plan to use MEGA, S3-like providers, Dropbox, OneDrive, SFTP, or Google Drive via rclone, install rclone:

Windows

Download & unpack from rclone.org/downloads or use Chocolatey/Scoop: 

# Chocolatey (if installed)
choco install rclone
# or Scoop
scoop install rclone

macOS / Linux

# macOS
brew install rclone

# Linux - follow https://rclone.org/install/

Configure a remote (example: Google Drive)

rclone config
rclone lsd gdrive:
rclone mkdir gdrive:KK

4) Developer extras required by Makefile (Windows build specifics)

goversioninfo

The Makefile runs goversioninfo inside cmd/kk to create a Windows resource (resource.syso) from versioninfo.json. Install it if you need to run make build on Windows: 

go install github.com/josephspurrier/goversioninfo/cmd/goversioninfo@latest

golangci-lint (optional)

Used by make lint/CI:

go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

make

On Windows, use Git Bash/MSYS2/WSL or install GNU Make (choco install make) or run the build commands manually.

5) Build KK (from source)

From the repository root:

Windows (PowerShell)

# Option A: direct build
go build -o kk.exe ./cmd/kk

# Option B: use Makefile (preferred for resource embedding)
make build

macOS / Linux

go build -o kk ./cmd/kk
# or
make build

After build, run:

# Windows
./kk.exe --version

# macOS/Linux
./kk --version

5a) Use a prebuilt executable (recommended for regular users)

If you don't want to build from source, use a prebuilt kk executable. This may be shipped with the project or distributed via release artifacts.

Windows (prebuilt kk.exe)

# Run directly
.\kk.exe --version

# Register the binary's folder on your user PATH (idempotent)
.\kk.exe install-path

# Or manually copy to a permanent folder
New-Item -ItemType Directory -Force "$env:USERPROFILE\bin"
Copy-Item .\kk.exe "$env:USERPROFILE\bin\kk.exe"
# Add to user PATH if not already present
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\bin", "User")

macOS / Linux

chmod +x kk
sudo mv kk /usr/local/bin/kk
kk --version

Security Notes

6) Install kk on your PATH (convenience)

The project provides kk install-path which edits your user PATH on Windows: 

# Build first
go build -o kk.exe .\cmd\kk

# Install on PATH
.\kk.exe install-path

# Open a new terminal and verify
Get-Command kk
kk --version

On macOS/Linux you may run ./kk install-path or manually copy the binary to a directory on your PATH (e.g., /usr/local/bin).

7) Configure a remote in KK

Option A — Native Google Drive (recommended, no rclone needed)

kk setup gdrive handles OAuth, creates the KK/ root folder on Drive, and registers the remote in .kk/config.json automatically. 

# Run once inside your kk repo (opens a browser for Google OAuth)
kk setup gdrive

# When prompted, give the profile a name (e.g. "work" or "personal")
# The default name is "default" — just press Enter to accept

# Output example:
# Connect Google Drive
# Opening browser for authorization...
# kk: Google Drive auth saved to ~/.config/KK/gdrive/default.json
# kk: Drive project folder-id: 1a2B3cD4eF5gH6iJ7kL8mN9oP0qR1sT2u
# kk: Run 'kk push' to create the project folder on Drive.
#     Share the project folder ID with teammates so they can clone:
#     kk clone drive:1a2B3cD4eF5gH6iJ7kL8mN9oP0qR1sT2u
# Remote ready.

⚠️ Note on Push Performance: The first push will be slow because it must upload all large files for the first time. By default, the Google Drive remote's verify_mode is set to "local-hash". You can change this to "none" or "download" in your .kk/config.json:

To update the remote settings: 

kk remote remove gdrive
kk remote add drive gdrive --drive-folder-id <id> --drive-auth-path <path> --verify-mode none

(Alternatively, you can manually edit the "verify_mode" value under the gdrive entry in your .kk/config.json file).

Once a push completes successfully:

  1. The successfully pushed HEAD commit is saved locally in .kk/push-state.json.
  2. On your next push, kk checks if the last pushed commit is an ancestor of the current commit.
  3. If it is, kk queries Git only for the changes since that commit.
  4. It will sync and verify only the specific file(s) and object(s) you changed (e.g., just the 1 modified file/object), making subsequent pushes near-instantaneous.

Multiple Drive Remotes

# First Drive remote
kk setup gdrive --name drive1 --account personal

# Second Drive remote (uses drive1's folder structure as base)
kk setup gdrive --name drive2 --account work

# Third Drive remote with specific folder
kk setup gdrive --name backup --folder ABC123 --account shared

Shared Drives or externally shared folders

kk setup gdrive --scope full
🔴 CRITICAL SECURITY WARNING

The --scope full flag grants KK permission to access ALL files in your entire Google Drive, including personal documents, photos, and sensitive data.

Only use this scope if:

Never use binaries from untrusted sources with this flag. See Privacy Policy for complete security details.

Note: kk setup gdrive registers the remote for you. You do not need to run kk remote add separately when using the native Drive backend.

Option B — Google Drive via rclone

Use this if you already use rclone or want more control over the rclone config.

Step 1 — configure rclone

rclone config
# Suggested values:
#   name>    gdrive
#   storage> drive
#   scope>   drive

Step 2 — add the remote to KK

# --remote must point to the PROJECT folder, not just a KK root
# Minimal form — only required flags
kk remote add rclone gdrive --remote gdrive:KK/MyGame --push true --pull true

# Full form — with optional metadata
kk remote add rclone gdrive \
  --display-name "Google Drive" \
  --role primary \
  --provider google-drive \
  --binary rclone \
  --remote gdrive:KK/MyGame \
  --verify-mode download \
  --priority 20 \
  --pull true \
  --push true \
  --tag cloud

Local NAS / external drive

# --path must point to the PROJECT folder, not just a KK root
kk remote add local nas --path /Volumes/NAS/KK/MyGame --push true --pull true

8) Running smoke tests and Makefile targets

Makefile useful targets

make build   # compile (runs goversioninfo on Windows)
make test    # go test ./...
make smoke   # ./scripts/smoke-test.sh
make fmt     # gofmt -w ./cmd ./internal
make lint    # golangci-lint run ./...
make clean   # remove built artifacts

Troubleshooting

Further Reading