title-tools

Offline Node CLI over the same engines as the Title Tools web app. It is also the execution layer for the Claude Code and Codex skills.

Build and run

pnpm --filter title-tools build
node packages/cli/dist/index.js --help

Project config and batch processing

After a local install, invoke the binary through the package manager:

pnpm exec title-tools --help
npx --no-install title-tools --help

The bare title-tools command is only available when the package's bin directory is already on PATH (for example after a global install). npx --no-install never downloads another version.

Typograph a whole project without a config:

npx title-tools typograph . --lang ru --write

The command recursively processes supported text, Markdown, markup, and source files. It preserves source syntax and Astro frontmatter and skips dependencies, caches, and common build-output directories.

When textKeys is omitted, TS/JS data strings are processed recursively in variables, objects, nested objects, and arrays. Imports, module paths, URLs, and executable syntax stay protected. Set textKeys to enable a strict allowlist; case-insensitive glob patterns such as *Title, *Description, *Label, and *Text are supported. A matched key opens its complete nested object or array. Markdown frontmatter keeps its conservative built-in text-key list.

Create an ESLint-style project config when you need custom file boundaries, several tasks, or a repeatable workflow:

npx title-tools init
npx title-tools run --dry-run
npx title-tools run content --explain
npx title-tools run content --check
npx title-tools run images
npx title-tools run

title-tools.config.mjs defines named tasks with their own include, exclude, and options:

/** @type {import('title-tools/config').TitleToolsConfig} */
export default {
  root: '.',
  exclude: ['**/node_modules/**', '**/dist/**', '**/generated/**'],
  tasks: {
    content: {
      command: 'typograph',
      include: ['src/**/*.{html,md,mdx,js,jsx,ts,tsx,vue,astro}'],
      exclude: ['**/*.generated.*'],
      // Omit textKeys for all safe TS/JS data strings. Add glob patterns to restrict keys.
      options: { lang: 'ru', write: true },
    },
    images: {
      command: 'image',
      include: ['public/images/**/*.{png,jpg,jpeg,webp}'],
      options: {
        format: 'webp',
        quality: 80,
        out: 'generated/images',
        preserveStructure: true,
        concurrency: 4,
      },
    },
  },
};

Patterns cannot escape the config root. Symlinks are not followed. Image output stays inside the root, and preserveStructure prevents collisions when hundreds of nested files share the same basename. Use --dry-run before a broad change. --explain reports processed, already-clean, and skipped TS/JS keys. --check never writes and exits with code 1 when typography changes are required.

Install an agent skill

Install only the integration you use:

npx title-tools install-skill claude
npx title-tools install-skill codex

Claude Code installs to ~/.claude/skills/title-tools; Codex installs to ~/.agents/skills/title-tools. Pass --force to replace an older installation. --out <directory> is available for project-local or test installations.

The distributable skill templates use the package name from this package.json, so renaming the package before publishing automatically updates generated commands.

Commands

init       Create title-tools.config.mjs
run        Run named config tasks over matched files
typograph  Typography for text, Markdown, and source files
svg        SVG optimization with precision/ID/color options
image      Image conversion, optimization, and <picture> sets
favicon    Favicon and PWA package generation
font       Font conversion, subsetting, and @font-face CSS
base64     Raw or WebP data URIs
srcset     Responsive width/density sets and fixed crops
clamp      Fluid CSS clamp() calculation
px-rem     PX ↔ REM conversion
color      HEX/RGB/HSL normalization
contrast   WCAG contrast checks
meta       SEO, Open Graph, and Twitter tags
tokens     Import, validate, merge, and export design tokens

typograph accepts files or directories. Dry runs distinguish matched files from files with actual changes. typograph and svg read stdin when no paths are passed; use --stdin-name page.astro when piping a known document type. Obvious Astro frontmatter is detected automatically. They only edit files with --write. Asset generators accept --out; calculation commands support --json where structured output is useful.