>_
worktale university

university / course 04

Advanced 6 lessons · ~50 min

Advanced CLI.

Worktale is scriptable. This course covers the pieces that matter when you want to integrate Worktale output into other tools, manage many repos, or generate narrated digests with a local LLM.

Lesson 4.1

Output formats.

WHAT YOU'LL LEARN

Use --format json, --format csv, and --format markdown to pipe Worktale into other tools.

Three commands support --format: log, digest, and session stats/session list. Short flag: -f.

JSON: for scripts and tooling

$ worktale log --days 7 --format json | jq '.rows | length'

42

$ worktale digest --format json

{ "date": "2026-04-17", "commits": [...], "summary": {...}, "modules": [...], "ai": {...}, "notes": [...] }

CSV: for spreadsheets

$ worktale log --days 30 --format csv > april.csv

# One row per commit: date, sha, message, author, timestamp, lines, files, branch

$ worktale session list --days 30 --format csv > ai-april.csv

# One row per session: date, tool, model, cost, input_tokens, output_tokens, duration

Markdown: for docs and commit-ready output

$ worktale digest --format markdown > week-recap.md

# Plain markdown without chalk color codes, safe to commit to a docs repo

KEY INSIGHT

When --format is set to anything other than the default, Worktale suppresses all interactive prompts (like “save this digest?”). Output is pure — safe to pipe, redirect, or capture in CI.

Lesson 4.2

Bulk import with batch.

WHAT YOU'LL LEARN

Import dozens of repos in one command — with or without hooks.

worktale batch recursively walks a directory, finds every git repo, and imports commit history for each. No hooks installed by default.

Most common use

# Import every repo under ~/code, last 3 months only, silently

$ worktale batch ~/code --since 3m --auto

✓ Processed 23 repos, imported 8,412 commits in 14s.

Useful flags

  • --since 6m / --since 2024-01-01 — limit how far back to scan
  • --annotate — also generate daily summaries for imported days (slower, but Overview tab will be populated)
  • --auto — skip confirmation prompts
  • --install-hooks — install hooks in every repo (default: off — batch is import-only)
  • --exclude 'node_modules|vendor' — skip paths matching a regex

GOTCHA

If a repo is deeply nested (e.g. a monorepo with submodules), batch will detect each inner .git and import them separately. Usually not what you want. Use --exclude or run worktale init at the outer repo only.

Lesson 4.3

Multi-repo with repos.

WHAT YOU'LL LEARN

How to list, rename, move, or remove tracked repos.

# List every tracked repo

$ worktale repos

# Rename a repo in your display

$ worktale repos rename acme-portal "Acme: Customer Portal"

# A repo moved on disk? Tell Worktale

$ worktale repos move my-saas-project /new/path/to/repo

# Stop tracking a repo (history is kept in the DB)

$ worktale repos remove side-experiment

Repos are identified by absolute path. Moving a folder on disk without running repos move means the post-commit hook still points at the old path; Worktale silently stops recording new commits until you fix it.

Lesson 4.4

Ollama-narrated digests.

WHAT YOU'LL LEARN

Wire a local Ollama model into worktale digest so your summaries are prosaic instead of templated. Everything stays on your machine.

Prerequisites

  1. Ollama installed (ollama.ai).
  2. A model pulled: ollama pull llama3.2 or similar.
  3. Ollama daemon running (ollama serve or system service).

Wire it up

$ worktale config set ai.provider ollama

$ worktale config set ai.model llama3.2

$ worktale config set ai.ollamaUrl http://localhost:11434

Run a narrated digest

$ worktale digest

⚡ WORKTALE DIGEST — April 17, 2026

Spent the afternoon on payments. The big win was tracking down a webhook race condition that had been masking a second bug in the retry logic — fixing the retry exposed it, then the idempotency-key constraint cleaned both up. Shipped 7 commits, net +815 lines, mostly in src/api/ and src/workers/.

The prompt that goes to Ollama is: “Given these commit messages and notes, write a 2-3 paragraph recap in first person. Don't fabricate.” No external network. No tokens billed. Output quality depends on your model; 7B+ models work well.

GOTCHA

If Ollama is not running when you digest, Worktale falls back to template mode and prints a one-line warning. No silent failures, no hangs.

Lesson 4.5

Hooks: install, uninstall, status.

WHAT YOU'LL LEARN

Manage the post-commit hook without touching .git/hooks/ by hand.

$ worktale hook status

Installed · /path/to/repo/.git/hooks/post-commit

$ worktale hook uninstall

Removed.

$ worktale hook install

Installed.

# Operate on a different repo

$ worktale hook install /path/to/other-repo

What the hook looks like

Three lines. You can read it. It shells out to worktale capture with the repo path and exits 0 so it never blocks a commit.

#!/bin/sh

# Worktale auto-capture

worktale capture "$PWD" > /dev/null 2>&1 &

The & backgrounds the capture so commits return instantly. If worktale is missing from PATH, the hook fails silently and your commit is unaffected.

Lesson 4.6

Config deep-dive.

WHAT YOU'LL LEARN

Every config key, what it does, and how to read/write config from the CLI or a file.

Config lives at ~/.worktale/config.json. You can edit it directly or use the CLI:

$ worktale config get # print entire config as JSON

$ worktale config get ai.model

$ worktale config set nudgeTime "18:30"

$ worktale config unset ai.model

Every key

nudgeTime"17:00" HH:MM for end-of-day nudge
timezone"auto" or IANA tz like "America/New_York"
ai.provider"template" (default) or "ollama"
ai.modelOllama model name, e.g. "llama3.2"
ai.ollamaUrlOllama base URL (default http://localhost:11434)
git.userEmailYour git email (usually auto-detected)
git.userEmailOverrideOnly count commits from this email
showCaptureConfirmationPrint a "✓ captured" line after git hook fires
cloudEnabledManaged by cloud login/logout commands
cloudApiUrlOverride for self-hosted cloud backend
appearance.themeDesktop app theme: "dark" or "light"
appearance.fontScaleDesktop app font scale: 0.9 / 1 / 1.15 / 1.3

KEY INSIGHT

Config is versioned automatically — backup created to ~/.worktale/config.json.bak before any set/unset. If you ever break it, delete config.json and Worktale regenerates defaults on next run.