profile

Manage the shared Apothem profile.

profile is a command group with four subcommands: init, show, set, and edit. The shared profile is the single source of truth that every harness adapter materializes into its native configuration.

SynopsisCopy Anchor Link

apothem profile init [--profile PATH] [--force]
                     [--quiet|-q] [--verbose|-v]
                     [--format plain|json] [--json] [--no-color]
apothem profile show [--profile PATH] [--quiet|-q] [--verbose|-v]
                     [--format plain|json] [--json] [--no-color]
apothem profile set KEY VALUE
                     [--profile PATH] [--quiet|-q] [--verbose|-v]
                     [--format plain|json] [--json] [--no-color]
apothem profile edit [--profile PATH] [--quiet|-q] [--verbose|-v]
                     [--format plain|json] [--json] [--no-color]

Common optionsCopy Anchor Link

Every subcommand accepts the shared options below.

SubcommandsCopy Anchor Link

profile initCopy Anchor Link

Create a schema-valid minimal profile scaffold at ~/.config/apothem/profile.yaml or --profile PATH. Existing files are preserved unless --force is supplied.

The scaffold's first line is a yaml-language-server modeline naming the profile schema's $id, https://apothem.ahmedgad.com/schemas/profile.schema.json. The site serves the packaged schema at that address, so an editor with YAML language support validates the profile while you edit it. Every packaged schema under src/apothem/schemas/ is served the same way at https://apothem.ahmedgad.com/schemas/<file>.

profile showCopy Anchor Link

Display the validated, default-expanded shared profile. With --json the document is the profile itself, led by schema_version: the profile schema version the engine read it as (see the JSON output contract).

profile set KEY VALUECopy Anchor Link

Set a key in the shared profile. KEY is a dotted path that descends into the nested profile (identity.name, preferences.style, enforcement.sprints, harnesses.<harness>.preferences.style); a single key with no dot sets a top-level node. VALUE is stored as a literal string — bare words are not coerced (no stays "no", 2024-01-01 and 1.0 stay strings) — except true/false (the boolean enforcement flags) and explicit [...]/{...} list/map input. The fully-assembled profile is validated against the schema before writing; an invalid set is refused and the profile on disk is unchanged.

profile editCopy Anchor Link

Open the shared profile in the system editor.

Validation errorsCopy Anchor Link

Every command that reads the profile validates it against the packaged schema and reports every problem it finds in one pass, so one edit can fix them all:

• Plain output names the first problem in full (Field, Reason, Fix, and Offending value (redacted): the input that failed, with secret-shaped values replaced by <redacted>; it is never a suggested replacement), then lists up to ten more under Other problems.
• JSON output keeps the first problem in the error object's top-level fields and adds an errors array with every problem (code, field, reason, fix, safe_value).
• Unknown keys echo only the unexpected key and its redacted value, not the whole profile.
• Managed-block markers. No key or text value may contain <!-- BEGIN APOTHEM MANAGED BLOCK --> or <!-- END APOTHEM MANAGED BLOCK -->. Apothem writes those markers around the block it manages in instruction files, and profile text lands inside that block, so a marker in it would split the block. Each such field fails with profile.managed_block_marker: field is its dotted path (for example rules.2 or mcp_servers.search.env.SEARCH_MODE) and reason names the marker. The value itself is never echoed (safe_value is null), since it may be a credential.

profile init (and every other command that scaffolds a profile) writes schema_version: 1. A profile without schema_version is read as version 1.

ExamplesCopy Anchor Link

apothem profile init
apothem profile init --profile ./profile.yaml --force --json
apothem profile show
apothem profile show --json
apothem profile set seriousness SHARED
apothem profile set rules '["Use fake placeholders in examples."]'
apothem profile edit

Exit codesCopy Anchor Link

See alsoCopy Anchor Link

• apothem install — materialize the profile into a harness
• apothem doctor — run system-wide install diagnostics