Public Command Surface

The public command surface is the set of terminal commands exposed by the canonical codealmanac script and its short ca alias. The package maps both console-script names to codealmanac.cli.main:main, so they share one parser, command behavior, output contract, and exit-code contract [@pyproject]. Parser modules define syntax only; the CLI adapter boundary explains how parsed commands cross into services and workflows.

The root parser registers three command families: run commands, wiki commands, and admin commands [@parser_root]. The admin family delegates to config, setup, diagnostics, update, jobs, and automation parser modules [@parser_admin]. It also exposes --version and lists the visible top-level command names in PUBLIC_COMMAND_METAVAR [@parser_root]. Hidden worker commands exist for internal scheduling and queue execution, but they are removed from visible choices and from rendered syntax guidance [@parser_run] [@syntax_catalog].

Parser failures go through the custom argument parser, which classifies syntax problems before the CLI renderer turns them into user-facing guidance [@parser_argument].

Top-Level Commands#

The run commands are covered in the workflow architecture pages. The exact machine-readable output surface is covered by JSON output contract.

automation has no install or uninstall subcommand; its status subcommand only filters and reports scheduled tasks, defaulting to all three when no task names are given [@automation_selection]. Scheduled tasks are changed through config set automation.<task>.enabled and config set automation.<task>.every, which reconcile that task's scheduler entry immediately, or through config apply after a direct edit to ~/.codealmanac/config.toml [@automation_jobs]. See Config keys for the full key set and Setup local automation for the operational path.

Hidden Commands#

Three top-level commands are intentionally hidden from normal help: __run-worker, __run-executor, and __garden-scheduler [@parser_run]. __run-worker requires --cwd and drains queued run work for a repository; for each queued run it spawns __run-executor <run-id>, which claims that one run and actually executes the operation so the worker process can keep draining the queue if the executor is cancelled [@parser_run]. __garden-scheduler is the scheduled garden entrypoint [@parser_run].

The update --scheduled flag is also hidden from help while remaining accepted by the update parser [@parser_updates]. These hidden entries are implementation entrypoints, not public user workflows.

Intentionally Absent Legacy Surface#

The parser rejects removed or unsupported flags because they are not registered. Tests assert that init --root, list --drop, search --include-archive, and search --archived render the CodeAlmanac Unknown option syntax screen rather than silently mapping to legacy behavior [@parser_argument] [@cli_tests].

That absence is part of the surface. New repos use the fixed almanac/ tree, registered repositories are not auto-dropped by list, and archive flags are not part of the current search parser. When adding a command, follow Add a CLI command and keep syntax in the parser family that owns the command.