Overview

Klaat (Kodelabs As A Thing) is a modern command-line tool written in Kotlin and compiled to native machine binaries using GraalVM. It serves as a spiritual successor to the archived Google Codelabs command-line tool (claat).

Klaat enables technical writers, software engineers, and educators to convert structured Markdown files and Google Documents into beautiful, step-by-step interactive tutorials called codelabs.

Key Capabilities

• Markdown & Google Docs Input: Generate tutorials using your favorite tools.
• Built-in Live Preview: Instantly check your work on a local Ktor web server.
• Zero Dependencies: Compiled directly to native machine code for instant startup and low memory usage.
• Flexible Publishing: Export to standalone HTML files, standard Markdown output, or fully self-contained offline packages.

Installation

Klaat is distributed as a single native binary for macOS (Apple Silicon only) and Linux. Choose one of the installation methods below.

Homebrew (macOS & Linux)

Homebrew is the easiest way to install and manage Klaat versions.

Stable Release

brew tap kartikarora/klaat
brew install klaat

Snapshot Builds (Develop Branch)

brew tap kartikarora/klaat-snapshots
brew install klaat-snapshot

Quick Start

Export your first codelab in three simple steps.

---
id: hello-world-tutorial
summary: An introductory tutorial
categories: General
status: Published
authors: Your Name
---

# Hello World Tutorial

## Step 1: Getting Started
Duration: 3

Welcome to this tutorial! 

## Step 2: Conclusion
Duration: 2

You are done!

klaat export hello.md -o output/

klaat serve -d output/

klaat help

The help command displays global help information, available subcommands, or detailed options for a specific subcommand.

klaat --help

klaat export --help

klaat serve -h

klaat version

Prints version metadata including release build name, commit hashes, target platform architectures, and Gradle dependencies.

klaat version

klaat install-skills

The install-skills command dynamically unpacks KLAAT codelab authoring skills and formatting instructions into existing AI coding agent folders in the project workspace or global directories.

klaat export

The export command reads a list of source files (Markdown or Google Docs IDs) and renders them into the specified output formats.

klaat export tutorial.md -o build/codelabs/

klaat export 1sK...J6g -o build/ -css https://example.com/custom.css

klaat serve

The serve command hosts your exported codelabs locally so that you can view them as they will appear when deployed.

klaat update

The update command scans an output directory, reads original resource paths from the metadata of existing codelabs, refetches the source (e.g., from Google Docs), and updates the rendered files in place.

klaat demo

The demo command extracts the bundled showcase demo codelab into the current working directory, exports it to HTML, and immediately launches the local preview server.

klaat demo

klaat demo --no-serve

Codelab Format Guide

The syntax schema, YAML frontmatter, Google Docs visual mappings, and supported rich elements are documented on a dedicated format guide page.

Google Docs Setup

To pull documents directly from Google Docs using document IDs, Klaat requires access permission tokens using OAuth Desktop App configurations.

1. Setup credentials.json

Create a file named gcp_credentials.json in the project root or copy it to the resources directory (src/main/resources/credentials/gcp_credentials.json):

{
  "installed": {
    "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uris": ["http://localhost"],
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token"
  }
}

2. Authentication workflow

On your first export command executing a Google Document ID source, Klaat will:

1. Launch your default web browser redirecting to Google Auth services.
2. Request user authorization confirming Read Access permissions for Google Docs.
3. Saves credentials locally within a file token storage: ~/.klaat/tokens/StoredCredential.

Differences from original claat

While Klaat serves as a spiritual successor with high flag compatibility, there are some differences:

• Built with Kotlin: Rewritten from Go into Kotlin. Relies on Flexmark and FreeMarker underneath.
• Auto-browser in serve: The serve command opens your browser automatically. Disable this with --no-browser.
• Storage Path: Authentication tokens are stored inside ~/.klaat/tokens/, whereas Go claat stores them in ~/.claat/ or browser configurations.