Config file

spanical reads one optional config file, spanical.config.ts, written in TypeScript:

import { defineConfig } from "spanical";
 
export default defineConfig({
    repos: [{ name: "my-repo", path: "~/code/my-repo" }],
});

defineConfig gives you typed options; the file is loaded by dynamic import and must have a default export. Without any config file, spanical analyses the git repository containing your current directory with default settings.

Discovery

From your working directory, spanical walks up until a directory contains either spanical.config.ts or a .git entry. That directory is the config location even when the file itself is absent, and it pins the cache path: the database always lives at <config dir>/.spanical/cache.db. An explicit --config path wins over discovery.

Schema

The schema is strict; unknown keys fail validation.

Details worth knowing:

• authors.emails accepts plain addresses; an address like 12345+login@users.noreply.github.com auto-bridges to its embedded GitHub login unless an entry overrides it
• tickets.github.token must be the literal string "env:GITHUB_TOKEN". The secret itself comes from the GITHUB_TOKEN environment variable at runtime
• tickets.github.includeIssues defaults to true; set false to sync pull requests only
• tickets.attribution picks who gets credit per ticket: "assignee" (default), "author", or "closer"

Validated example

This exact shape loaded successfully through the CLI during development:

import { defineConfig } from "spanical";
 
export default defineConfig({
    repos: [
        // name is the label everywhere in reports; path is any git worktree
        { name: "alpha", path: "~/code/alpha" },
        {
            name: "beta",
            path: "~/code/beta",
            branch: "main",
            github: "acme/beta-fork",
        },
    ],
    since: "2026-01-01",
    timezone: "America/New_York",
    exclude: ["**/*.lock", "**/dist/**", "**/.next/**", "**/*.snap", "**/*.md"],
    authors: {
        "dev-one": { emails: ["dev1@example.com"] },
        "dev-two": { emails: ["dev2@example.com"], github: ["dev-two-gh"] },
        "dev-three": { emails: ["dev3@example.com"] },
    },
    hotspot: { minFileLines: 20, busFactorThreshold: 0.9 },
    reworkWindowDays: 30,
    tickets: {
        source: "github",
        github: { token: "env:GITHUB_TOKEN" },
        attribution: "assignee",
    },
});

Errors

All config errors print one message and exit 1: