How To Guide

A simple guide for regular users to get started with KK for managing large files in game projects.

Initialize a new project
Add a GitHub/GitLab/Gitea remote
Use Google Drive only
Use Google Drive and Rclone (multiple backends)
Use multiple Google Drive remotes
Clone a project
Share Drive folder requiring full access scope
Migrate between Git remote and storage-bundle modes
Daily Workflow
Troubleshooting
Commands Reference

Initialize a new project

Create a new KK repository in your project directory:

cd MyGame
kk init

This creates:

.kk/git/ - Git database (instead of .git/)
.kk/objects/ - Local cache for large files
.kk/config.json - KK configuration
.kk/tracks.json - File patterns to track
.kkignore - Files KK should ignore

Add a GitHub/GitLab/Gitea remote

KK can sync pointer history to git hosting services while storing large files separately.

Add GitHub remote

kk remote add git github https://github.com/your-username/MyGame.git

Add GitLab remote

kk remote add git gitlab https://gitlab.com/your-username/MyGame.git

Add Gitea remote (self-hosted)

kk remote add git gitea https://git.example.com/your-username/MyGame.git

Set as default remote

kk remote set-default github

Verify remote

kk remote check github
# ok github  git remote configured (https://github.com/your-username/MyGame.git)

Use Google Drive only

The simplest setup - store everything on Google Drive.

Step 1: Initialize your project

cd MyGame
kk init

This creates the KK directory structure with embedded Git database.

Step 2: Set up Google Drive

kk setup gdrive

This opens a browser for OAuth authorization. After successful authorization:

# kk: Google Drive auth saved to ~/.config/KK/gdrive/default.json
# kk: Drive remote 'gdrive' configured with folder-id: 1a2B3cD4eF5gH6iJ7kL8mN9oP0qR1sT2u
# kk: Run 'kk push' to upload your project to Drive.
#     Share the project folder ID with teammates so they can clone:
#     kk clone drive:1a2B3cD4eF5gH6iJ7kL8mN9oP0qR1sT2u
# Remote ready.

Tip: Finding your folder ID manually

To find the folder ID in Google Drive:

Open the folder in Google Drive in your browser
Look at the URL — it will be in the format: https://drive.google.com/drive/folders/<FOLDER_ID>
Copy the <FOLDER_ID> portion (a long alphanumeric string)

Example: In https://drive.google.com/drive/folders/1a2B3cD4eF5gH6iJ7kL8mN9oP0qR1sT2u, the folder ID is 1a2B3cD4eF5gH6iJ7kL8mN9oP0qR1sT2u.

Step 3: Track large files (Optional)

By default, KK automatically tracks all files that are not recognized as code (such as .unitypackage, .uasset, .fbx, .png, .wav, etc.) as pointer files. Therefore, you can skip this step!

Explicitly running kk track is only necessary if you want to configure custom tracking patterns:

kk track "*.mp4" "*.png" "*.fbx" "*.zip"

Step 4: Work normally

# Add large files (converts to pointers)
kk add Assets/cinematic.mp4

# Commit
kk commit -m "add cinematic"

# Push to Drive
kk push

⚠️ 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:

"local-hash" (default): Verifies files using cached local hashes.
"none": Skips downloading/hashing and performs a quick metadata existence check (only checking if the file is present on Drive).
"download": Downloads the full bytes of every object during checks to verify its SHA-256 hash. Note: If you have large files, this mode is very slow.

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:

The successfully pushed HEAD commit is saved locally in .kk/push-state.json.
On your next push, kk checks if the last pushed commit is an ancestor of the current commit.
If it is, kk queries Git only for the changes since that commit.
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.

Step 5: Share with teammates

Why sharing is required: Google Drive folders created by KK are owned by your Google account. For teammates to clone and sync files from this folder, you must explicitly share it with their Google accounts through Google Drive's sharing settings.

How to share:

Open Google Drive and locate the KK folder (usually named after your project)
Right-click the folder and select "Share"
Add your teammates' Google account email addresses with "Editor" permissions
Share the folder ID with your team

Once shared, teammates can clone the repository using:

kk clone drive:<folder-id> --pull

⚠️ Important - Scope Requirements:

By default, KK uses the drive.file scope, which only allows access to files KK creates. Since your teammates did not create the shared folder, they must use the full drive scope to clone it.

Teammates must run:

kk setup gdrive --scope full

🔴 CRITICAL SECURITY WARNING

The --scope full flag grants KK access to ALL files in your entire Google Drive, not just KK folders.

Only use if you:

Need access to shared folders you didn't create
Fully trust the KK binary with complete Drive access
Verified the binary is official or reviewed the source code

See our Privacy Policy for complete security details and how to revoke permissions.

This grants KK permission to access shared folders and Shared Drives. Security note: --scope full allows KK to access all files in the user's Google Drive, not just KK-created files. See our Privacy Policy for details about scope permissions and security implications.

Troubleshooting:

Error: "Folder not found" or "Permission denied" → Teammate needs to use --scope full (see above)
Error: "Access denied" → Check that the folder is shared with the teammate's exact Google account email
Clone succeeds but no files download → Run kk pull after cloning to fetch the latest objects

Use Google Drive and Rclone (multiple backends)

Use multiple storage providers for redundancy - one Drive remote, one rclone remote (could be Dropbox, MEGA, S3, OneDrive, etc.).

What is rclone?

rclone is a command-line tool that syncs files to and from 70+ cloud storage providers. If you already use rclone, or want to use a provider that KK doesn't support natively, this is your option.

Supported providers: Dropbox, MEGA, Amazon S3, Wasabi, Backblaze B2, OneDrive, Google Drive, Box, pCloud, and many more.

Step 0: Install rclone (one-time setup)

Important: KK looks for rclone (or rclone.exe on Windows) in your system PATH. You can also specify the exact binary location when adding the remote.

Windows (for regular users)

Go to rclone.org/downloads
Download the Windows amd64 zip file
Unzip the downloaded file
Copy rclone.exe to one of these locations:

Where to put rclone.exe on Windows:

Choose ONE of these options:

C:\Users\YourName\AppData\Local\Programs\KK\ — Same folder as kk.exe (recommended!)
C:\Users\YourName\bin\ — A user bin folder
C:\Tools\rclone\ — Any folder you create, then add to PATH

Test it works: Open a NEW terminal (important!) and run:

rclone version

If you see version info, you're all set! If you get "command not found", make sure rclone.exe is in a folder on your PATH.

Quick install with package managers:

# Windows with Chocolatey
choco install rclone

# Windows with Scoop
scoop install rclone

# macOS
brew install rclone

# Linux
sudo apt install rclone     # Debian/Ubuntu
sudo yum install rclone     # RHEL/CentOS/Fedora

Step 1: Configure Google Drive

kk setup gdrive --name personal

Step 2: Configure rclone

First, set up your cloud provider in rclone. This is a one-time setup per provider:

rclone config

You'll see an interactive menu. Here's how to use it:

Type n and press Enter (for "New remote")
Enter a name like mega, dropbox, or s3
Choose the storage type by number or name (see list below for common providers)
Follow the provider-specific instructions
Type n for "No advanced config" (keep it simple!)
Type y to confirm, then q to quit when done

Common rclone storage types:

Provider	Type to enter	Suggested name
Dropbox	`dropbox` or type `6`	`dropbox`
MEGA	`mega` or type `8`	`mega`
Amazon S3	`s3` or type `4`	`s3`
Wasabi	`s3` → choose "Wasabi"	`wasabi`
Backblaze B2	`b2` or type `9`	`b2`
OneDrive	`onedrive` or type `23`	`onedrive`
pCloud	`pcloud` or type `22`	`pcloud`
Box	`box` or type `10`	`box`

Test your rclone configuration:

# Test connection - list root folders
rclone lsd mega:

# Create a test folder
rclone mkdir mega:KK-Test

# Verify it was created
rclone lsd mega:KK-Test

Step 3: Add rclone remote to KK

With rclone configured, add it as a KK remote:

Basic form (simplest):

kk remote add rclone mega --remote mega:KK/MyGame --push true --pull true

With custom rclone binary location (Windows):

If rclone.exe is not on your PATH, specify the full path:

# Full path to rclone.exe
kk remote add rclone mega \
  --remote mega:KK/MyGame \
  --binary "C:\Tools\rclone\rclone.exe" \
  --push true \
  --pull true

Or if rclone.exe is in the same folder as kk.exe:

kk remote add rclone mega \
  --remote mega:KK/MyGame \
  --binary rclone.exe \
  --push true \
  --pull true

Full form with all options:

kk remote add rclone mega \
  --display-name "MEGA Backup" \
  --role backup \
  --provider mega \
  --remote mega:KK/MyGame \
  --binary rclone \
  --verify-mode download \
  --priority 50 \
  --push true \
  --pull true

Complete Examples by Provider

Example: Dropbox + Google Drive

# 1. Set up Google Drive
kk setup gdrive --name personal

# 2. Configure Dropbox in rclone
rclone config
# → Choose "dropbox" storage
# → Follow OAuth in browser
# → Name it "dropbox"

# 3. Test Dropbox
rclone lsd dropbox:

# 4. Add Dropbox to KK
kk remote add rclone dropbox --remote dropbox:KK-Projects/MyGame --push true --pull true

# 5. Set priority (Drive is faster, use it first)
kk remote set-default personal

Example: MEGA + Google Drive

# 1. Set up Google Drive
kk setup gdrive --name personal

# 2. Configure MEGA in rclone
rclone config
# → Choose "mega" storage
# → Enter MEGA username/password
# → Name it "mega"

# 3. Test MEGA
rclone lsd mega:

# 4. Add MEGA to KK
kk remote add rclone mega --remote mega:KK/MyGame --push true --pull true

# 5. Push to both
kk push --all-remotes

Example: Wasabi S3 + Google Drive

# 1. Set up Google Drive
kk setup gdrive --name personal

# 2. Configure Wasabi in rclone
rclone config
# → Choose "s3" storage
# → Choose "Wasabi" as the S3 provider
# → Enter Wasabi access key and secret
# → Enter bucket name or let rclone create one
# → Name it "wasabi"

# 3. Test Wasabi
rclone lsd wasabi:

# 4. Add Wasabi to KK
kk remote add rclone wasabi --remote wasabi:my-bucket/MyGame --push true --pull true

# 5. Set priorities (Drive is primary, Wasabi is backup)
kk remote set-default personal

Example: OneDrive + Google Drive

# 1. Set up Google Drive
kk setup gdrive --name personal

# 2. Configure OneDrive in rclone
rclone config
# → Choose "onedrive" storage
# → Follow OneDrive OAuth in browser
# → Choose "OneDrive Personal" or "Business"
# → Name it "onedrive"

# 3. Test OneDrive
rclone lsd onedrive:

# 4. Add OneDrive to KK
kk remote add rclone onedrive --remote onedrive:KK/MyGame --push true --pull true

Step 4: Configure default remote and priority

# Set primary storage
kk remote set-default personal

# Check configuration
kk remote list

Your .kk/config.json will have:

personal (Drive) with priority 20 (default)
mega (rclone) with priority 50 (backup)

When pulling, KK tries remotes in priority order and falls back if one fails.

Step 5: Push to all remotes

kk push --all-remotes

This uploads to all push-enabled remotes.

Rclone Troubleshooting

Issue: "rclone not found" or "command not found"

Cause: KK can't find rclone in your PATH.

Fix:

Test if rclone is installed: rclone version
If not found, put rclone.exe in the same folder as kk.exe
Or specify the full path when adding the remote: --binary "C:\path\to\rclone.exe"

Issue: "Failed to list remote" or "connection failed"

Cause: rclone can't connect to the provider.

Fix:

Test connection: rclone lsd remote-name:
If credentials expired, reconfigure: rclone config
Check internet connection

Use multiple Google Drive remotes

Store your project on multiple Google Drive accounts or folders.

Scenario: Personal + Work Drive

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

# Second Drive - work account
kk setup gdrive --name drive2 --account work

# Third Drive - shared folder with team
kk setup gdrive --name shared --folder ABC123XYZ --account work

Each remote gets its own configuration:

kk remote list
# drive1  type=drive display_name="Google Drive"
# drive2  type=drive display_name="Google Drive"
# shared  type=drive display_name="Google Drive"

Push to specific remote

kk push --remote drive1

Push to all Drive remotes

kk push --all-remotes

Set default remote

kk remote set-default drive1

Clone a project

Clone from Google Drive

Get the folder ID from the project owner, then:

kk clone drive:<folder-id> --pull

The --pull flag automatically downloads and materializes large files.

Clone from local NAS

kk clone local:/Volumes/NAS/KK/MyGame --pull

Clone from rclone

kk clone rclone:gdrive:KK/MyGame --pull

Clone with Git remote history

If the project uses a Git remote for pointer history:

kk clone git:https://github.com/user/repo.git --pull
kk clone git:https://gitlab.com/user/repo.git --branch feature-or-test --pull

Clone into current directory

Use --here to clone without creating a subdirectory:

kk clone drive:<folder-id> --here --pull

The directory must be empty (except for the kk binary).

Share Drive folder requiring full access scope

Some Google Drive configurations require full drive access, especially when:

Working with Shared Drives (Team Drives)
Using folders shared by others with restricted privacy settings

Step 1: Authorize with full scope

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:

You need to access Shared Drives or externally shared folders
You fully trust the KK binary you are running
You verified the binary is from official releases or reviewed the source code

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

This requests the https://www.googleapis.com/auth/drive scope.

Step 2: Clone the project

Teammates must also authorize with full scope before cloning:

# Each teammate runs once:
kk setup gdrive --auth-only --scope full --account <profile-name>

# Then clone:
kk clone drive:<folder-id> --account <profile-name>

🔴 Security Reminder: All teammates using --scope full must trust the KK binary. Only use official releases or verified source builds.

Multiple accounts with full scope

# Authorize work account with full scope
kk setup gdrive --auth-only --scope full --account work

# Authorize personal account with full scope
kk setup gdrive --auth-only --scope full --account personal

# List all accounts
kk accounts

Migrate between Git remote and storage-bundle modes

⚠️ EXPERIMENTAL FEATURE WARNING

The kk remote migrate command is HIGHLY EXPERIMENTAL and may not work correctly in all situations.

Use with caution: This feature may cause data loss or corruption. Always backup your repository before attempting migration.

Known limitations:

Migration between modes may not preserve all commit metadata
Complex branch structures may not migrate correctly
Team coordination is required — all members must be aware of mode changes
Rolling back a migration may require manual intervention

Recommended: Test migration on a copy of your repository first before migrating your production project.

KK supports two distinct modes for managing and syncing commit history. You can migrate between them at any time:

Storage bundles: History is bundled and uploaded to object remotes. Active when no git-type remote is configured.
Git remote: History is pushed and pulled directly to/from a Git hosting service.

Storage bundles to Git remote (`to-git`)

If you started with storage bundles and now want to collaborate via GitHub:

kk remote migrate to-git github https://github.com/your-username/MyGame.git

This verifies connectivity, adds the git remote, and pushes all local branches.

Git remote to Storage bundles (`to-storage`)

If you want to move away from Git hosting and rely solely on object storage:

kk remote migrate to-storage

This uploads the full history bundle chain to your push-enabled object remotes and removes the Git remote configuration.

Daily Workflow

# Track new large file types
kk track "*.ogg" "*.wav"

# Add files (converts large ones to pointers)
kk add .

# Commit changes
kk commit -m "update assets"

# Push to default remote
kk push

# Or push to specific remote
kk push --remote drive2

# Or push to all remotes
kk push --all-remotes

Troubleshooting

Account expired

If you see authentication errors:

# Re-authenticate
kk setup gdrive --account <profile-name>

Remote not accessible

kk remote check <remote-name>

Missing large files

# Check object status
kk fsck

# Download missing files
kk pull-file .

List all configured remotes

kk remote list

Commands Reference

# Project management
kk init                                          # Initialize new KK repo
kk status [--json]                               # Show repo status
kk track "<pattern>"                            # Track file patterns
kk track list                                   # List tracked patterns
kk untrack "<pattern>"                          # Untrack pattern

# File operations
kk add <file>...                                # Add files (large → pointers)
kk commit -m "message"                          # Commit changes
kk push [--remote <name>] [--all-remotes]       # Push to remotes
kk pull                                          # Pull from git remote or history bundles
kk pull-file [--force] <file>...                 # Download large files
kk dematerialize <file>...                      # Revert to pointer

# Remotes
kk setup gdrive [--name <name>] [--account <profile>] [--folder <folder-id>] [--scope file|full] [--auth-only]
kk accounts [--json]                           # List Drive accounts
kk accounts --delete <profile> [--json]          # Delete account
kk remote add <type> <name> [options]           # Add remote
kk remote list [--json]                         # List remotes
kk remote set-default <name>                    # Set default remote
kk remote check <name> [--json]                  # Check remote
kk remote remove <name>                         # Remove remote
kk remote rename <old> <new>                      # Rename remote
kk remote migrate <to-git|to-storage> [options]  # Migrate history storage mode

# Clone
kk clone <spec> [--dest <dir>] [--remote-name <name>] [--pull] [--history] [--account <profile>] [--here]

Quick Reference Card

Personal project with Drive backup:

kk init
kk setup gdrive
kk track "*.mp4"
kk add . && kk commit -m "init" && kk push

Team project with multiple remotes:

kk init
kk setup gdrive --name drive1 --account team
kk remote add rclone backup --remote mega:KK/Project --push true --pull true
kk remote set-default drive1
kk track "*.fbx"
kk add . && kk commit -m "init" && kk push --all-remotes

Clone teammate's project:

kk clone drive:<folder-id> --account work --pull
cd MyGame
kk pull-file .

Connect to shared folder with full scope:

kk setup gdrive --name shared --folder <folder-id> --scope full --account work

🔴 Warning: --scope full grants full Google Drive access. Only use with trusted binaries from official sources.