az-cli

Helpers for building, cleaning, updating, and publishing projects, plus exporting and analysing AI session transcripts.

Requires Node.js 20 or newer. Yarn 4.6.0 is pinned in package.json and included in .yarn/releases.

node .yarn/releases/yarn-4.6.0.cjs install --immutable
node .yarn/releases/yarn-4.6.0.cjs typecheck
node .yarn/releases/yarn-4.6.0.cjs test
node .yarn/releases/yarn-4.6.0.cjs build
node dist/cli/index.js --help

With Yarn available on PATH, the equivalent commands are yarn install --immutable, yarn typecheck, yarn test, and yarn build.

yarn build-dev compiles the CLI and copies optional assets from temp/ into dist/. yarn start watches source and asset changes. Builds use TypeScript directly and preserve source maps.

Commands

| Command | Behavior | | --- | --- | | build [mode] | Build an inferred project, or select php, yarn, python, or docker. Docker builds also start Compose services. | | clean build | Remove build/ and dist/ in the selected project. | | clean all | Also remove dependencies, caches, and lockfiles. | | up [target..] | Update dependencies; Yarn targets may be omitted or repeated. | | publish | Publish a Yarn or Python package. Yarn packages are built first. | | package prepare | Generate the workspace's core package before building. | | package finalize | Generate publishable manifests in dist/, build/, or temp/. | | package publish | Publish the prepared packages. | | package go | Prepare, build, finalize, then publish; stop on the first failure. | | transcripts <claude\|codex> | Export sessions to Markdown with an index.json. | | optimize-transcripts <claude\|codex> | Prepare a transcript snapshot and run the selected analysis agent. | | verify-changes | Run the checks from .azcli/verify.json that match files changed since the base ref. First restores HEAD's line endings in modified files whose CRLF/LF endings were changed. Reports passed, failed, or not-run; exits 1 on failure (--strict also on not-run). --profile, --base, --json, --no-fix (skip the line-ending restore). | | restore-line-endings | Only restore HEAD's line endings in modified files whose CRLF/LF endings were changed (the first step of verify-changes). --path. | | install-skills | Copy the skills shipped in the package (skills/) into ~/.claude/skills. --target picks another directory. In this repository, yarn install-skills builds and runs it without publishing. | | worktree start <path> | Install the worktree's locked dependencies, pick a free port above the configured default, run the dev server detached, and wait for it to answer or exit. Reports URL, pid, compile result, and log file (inside the git dir). Fails at once if the process exits; --timeout bounds the wait. --page, --port, --skip-install. | | worktree status <path> | Branch tips and dirty files of the worktree and the target, ahead/behind counts, whether the branch is merged, and dependency manifests changed on each side. | | worktree sync <path> --direction in|out|both | Merge the target into the worktree branch (in) and/or the branch into the target (out). Refuses dirty trees; on conflict stops with the merge in progress and writes base/ours/theirs copies under the git dir, flagging whitespace-only conflicts. Never resolves conflicts; exits 1 on conflict. | | browser-check [directory] | Start the selected project's dev server, wait for readiness, and run its browser-test script with the server origin in BASE_URL. --tags, --headed, --url, --json. |

Worktree commands read .azcli/worktree.json from the worktree, else from --project; run azcli worktree start --help for the format. All three accept --target and --json.

Project commands accept --path to select a working directory. Build, update, clean, and publish accept --type, direct flags such as --python, and exclusions such as --nopython or --no-python. Use --quiet to suppress progress. Errors go to stderr and cause a nonzero exit status.

External tools must already be available on PATH. Commands run with explicit argument arrays and working directories. On Windows, standard Node and Composer .cmd/.bat shims are resolved to their entry points without a command shell. Custom batch launchers are rejected with an explanatory error.

Production Composer installation (up --prod and WordPress builds) preserves the lockfile and installs with --no-dev. Normal Composer updates retain the existing dependency-refresh behavior. Python build/publish expands distribution files explicitly.

Browser checks

azcli browser-check ./worktrees/order --tags "@shipping and not @save"
azcli browser-check --path ./web --url http://localhost:3001 --tags "@shipping" --headed

The directory defaults to the current directory and does not need to be a Git repository. All browser-check configuration lives in .azcli/browser.json. Without --url, startup installs locked project dependencies, picks a free port above the configured default, and waits for the server. Exited, timed-out, or failed-compilation servers stop the browser checks before the test command runs. Started servers remain running after success or test failure; the command prints their URL, pid, and log location. Logs are written to .azcli/logs/browser/ in the selected directory; add .azcli/logs/ to that project's .gitignore. --skip-install, --port, --page, and --timeout control startup.

Use --url for an already-running server; this skips installation and startup. Its availability is checked by the project's tests. The server's origin (scheme, host, and port, without the page path) is passed as BASE_URL. --headed sets HEADED=1; project browser hooks must read that variable to show the browser.

By default, browser checks run yarn test:browser in the selected directory. Configure the test command and server together in .azcli/browser.json (this example assumes the application's start script reads PORT):

{
  "command": "yarn",
  "args": ["test:browser"],
  "baseUrlEnv": "BASE_URL",
  "report": "cucumber-report.html",
  "install": {
    "command": "yarn",
    "args": ["install", "--immutable"]
  },
  "dev": {
    "command": "yarn",
    "args": ["start"],
    "defaultPort": 3000,
    "portEnv": "PORT",
    "readyPath": "/",
    "timeoutSeconds": 120,
    "pages": { "order": "/order" }
  }
}

command is required when the file exists; args defaults to an empty array. Optional cwd selects a directory inside the selected project. report is relative to that test working directory and must stay inside it. baseUrlEnv defaults to BASE_URL. Config is read from the selected directory, falling back to --project; fallback configuration still runs against the selected directory. Tags are appended as --tags <expression> without shell parsing. For npm scripts, use "command": "npm", "args": ["run", "test:browser", "--"].

dev is required for startup; without a config or dev, supply --url. install is optional and defaults to yarn install --immutable at the selected directory. Both accept command, args, and optional cwd relative to that directory. dev.defaultPort defaults to 3000; startup picks the first free port above it unless --port is supplied. dev.portEnv defaults to PORT, and {port} in dev arguments is replaced with the selected port. dev.readyPath defaults to /, timeoutSeconds to 120, and binDirs to ["node_modules/.bin"]. --page selects a named path from dev.pages; it affects the reported server URL, while BASE_URL remains the origin. Optional compiledPattern and failedPattern customize regexes matched against the dev log. Worktree configuration is never read by browser-check.

The target application owns its .feature files, Cucumber step definitions, authentication, fixtures, and cleanup. For example, its package.json can define "test:browser": "cucumber-js". Its browser hook should create a Playwright context with baseURL: process.env.BASE_URL and launch with headless: process.env.HEADED !== '1'. Configure Cucumber's HTML formatter to write the same file named by report; azcli reports its path when that file exists after a successful run. Test failures propagate to exit code 1. --quiet suppresses progress and subprocess output; --json returns server details and captured test output on success, while failures use the normal CLI error handler.

@cucumber/cucumber (12.x, compatible with Node.js 20) and @playwright/test are optional dependencies of azcli. Other commands do not import them, so they work when optional dependencies are omitted. Browser binaries are a separate setup step (yarn playwright install chromium in the application). The application's test script and step definitions must have their own resolvable Cucumber/Playwright dependencies, usually declared as its dev dependencies; installing azcli globally does not expose its optional packages to another project's module resolution. No packages or browser binaries are installed automatically by browser-check beyond its configured dependency install.

Transcript options

Use --project <text> repeatedly to filter projects, --since-days 0 to include all dates, and --last N to select the newest N matched sessions across projects. --list lists without exporting. Rendering supports --user-only, --no-include-tools, --no-include-thinking, and --include-subagents.

Optimization accepts --in for an existing export. It copies only indexed sessions to a fresh analysis directory before redacting them, preserving the original export. --out must name an empty directory; omitted output paths receive a unique suffix. --dry-run prepares the redacted snapshot and prints the agent command without launching it. Secret removal covers known project .env values and secret-like assignments, including summaries in the index.

Source layout

src/
  cli/                         entry point, registration, shared CLI options
  core/                        subprocesses, files, JSON guards, logging, project detection
  features/
    build/ clean/ update/ publish/ package/
    transcripts/               extraction, rendering, types, JSONL readers
      sources/                 Claude and Codex adapters
    optimize-transcripts/      snapshots, redaction, prompts, agent execution
tests/
  fixtures/                    synthetic JSONL sessions
scripts/                       build and test entry points

Each feature owns a typed yargs command module and its implementation. Shared subprocesses use core/process.ts; feature code lets failures reach the CLI boundary. Tests use temporary project fixtures and injected command runners, so the suite does not publish packages or run Docker/AI services. The test script type-checks tests and source, discovers every tests/*.test.ts, and keeps temporary files inside the project.