ak config prefs set

Use ak config prefs set to pin one Hook soft-preference, the journal.auto preference, or the worktree.root default location in the user config or the current project's config. The command changes the selected file immediately; it does not unregister or install a Hook and does not stop explicit /ak:journal.

Usage

ak config prefs set <key> <true|false>

Supply exactly two positional arguments.

Command flag

Shared flags are described in CLI conventions. The write does not prompt, so --yes and --no-interactive do not change it. There is no --dry-run, --force, or preview mode.

Key and value validation

Three key shapes are accepted:

• hooks.<name> — <name> must be a lowercase kebab-case Hook script basename matching ^[a-z0-9]+(?:-[a-z0-9]+)*$ and cannot contain another dot.
• journal.auto — the exact literal, no nested keys under journal.
• worktree.root — the exact literal, no nested keys under worktree.

For hooks.<name> and journal.auto the value must be the exact lowercase literal true or false. For worktree.root the value is a filesystem path; project scope only accepts a relative path (resolved against the project root), while user scope accepts either a relative path (also resolved against the project root) or an absolute path.

ak config prefs set hooks.simplify-gate false
ak config prefs set hooks.simplify-gate true --scope project
ak config prefs set journal.auto false
ak config prefs set worktree.root /Volumes/Portable/agentkit-worktrees
ak config prefs set worktree.root ../my-app-worktrees --scope project

Keys such as keys.anthropic, api.token, telemetry.enabled, hooks.Bad-Name, hooks.a.b, any journal.<other>, and any worktree.<other> are rejected before a preference write. This allowlist prevents the command from being used as a general secret or config editor.

For a Hook toggle, false lets a Hook that honors this preference exit early on its next run; true records the opposite preference. Harness registration is unchanged, and setting a name does not prove that Hook is installed.

For journal.auto, false suppresses the automatic /ak:journal step at the end of plan, cook, fix, ship, and bootstrap workflows without unregistering hooks or blocking an explicit /ak:journal. true records the opposite preference. The built-in default is true.

For worktree.root, the value picks the default location that ak:worktree uses when --worktree-root is not passed. Project scope refuses an absolute value with a warning and falls through to the next scope, because a committed project config can arrive from an untrusted clone. User scope accepts an absolute path, which is the right choice for a portable-drive or external-volume worktree layout. The built-in default is unset, so ak:worktree continues to fall back to the WORKTREE_ROOT environment variable and its built-in location chain.

Scope and filesystem effects

The writer changes only the selected hooks.<name>, journal.auto, or worktree.root leaf. It preserves other sections, unmodelled YAML, comments, key order, and the schema editor directive. If hooks, journal, or worktree already exists but is not a mapping, the write is refused.

Before writing, AgentKit validates the whole candidate against the schema embedded in this binary. Existing legacy spellings can produce warnings but do not by themselves fail validation; schema errors leave an existing target untouched.

Backup, atomicity, and recovery

When the target exists, AgentKit copies its current bytes to a mode-0600 file under $AGENTKIT_HOME/backups/config/. User backups begin with config-; project backups begin with project-config-. Backup failure aborts the config rewrite.

The new document is written to a sibling temporary file, changed to mode 0600, then renamed over the target. This prevents readers from seeing a half-written document.

To recover, stop other writers, inspect the backup_path reported by the successful command, manually replace config_path with that backup, and run ak config prefs validate. These config copies are not full AgentKit snapshots and have no automatic rollback command.

Human and JSON output

Human success writes the change and target path to stdout, followed by the backup path when one was created:

set hooks.simplify-gate = false (user scope) in /home/user/.agentkit/config.yaml
backed up prior config to /home/user/.agentkit/backups/config/config-<timestamp>.yaml

--json writes a raw object, not the shared success envelope:

{
  "action":"set",
  "key":"hooks.simplify-gate",
  "value":false,
  "scope":"user",
  "config_path":"/home/user/.agentkit/config.yaml",
  "backup_path":"/home/user/.agentkit/backups/config/config-<timestamp>.yaml",
  "found":true
}

backup_path is omitted when no backup was created. found is always true for a successful set. --quiet does not suppress this command-specific stdout.

Runtime failures do not emit the shared JSON error envelope and can be silent under --json; use process status and validate the expected fields. Flag-parse errors can remain plain-text usage. A wrong positional-argument count follows the generic runtime error path instead.

Exit behavior

Verify the result

ak config prefs resolve --json
ak config prefs validate

For project scope, run resolve from that same project directory so the intended project file participates in precedence.

Related commands

• CLI conventions