ak config prefs unset

Remove one scoped hook, journal.auto, worktree.root, agent model, or semantic_decision preference, understand fallback behavior, and recover from the reported config backup.

Use ak config prefs unset to remove an explicit hooks.<name> toggle, the journal.auto leaf, the worktree.root leaf, one agent_models.<runtime>.<tier> override, or one semantic_decision leaf from one config scope. The preference then inherits the value from the other scope when one exists, or uses its built-in default (journal.auto defaults to true; worktree.root defaults to unset, so ak:worktree falls back to WORKTREE_ROOT and the built-in location chain; an agent model override falls back to that adapter's built-in catalog default).

semantic_decision does not follow that precedence. Removing the user semantic_decision.enabled returns it to the default false, which disables the provider. Removing a project semantic_decision restriction restores the user policy for that project; it never grants consent.

Usage

ak config prefs unset <key>

The command requires exactly one positional argument. The key must be one of hooks.<name> (where <name> is a lowercase kebab-case hook script name), the exact literal journal.auto, the exact literal worktree.root, or agent_models.<runtime>.<tier> where <runtime> is the closed set cursor and <tier> is one of inherit, sonnet, opus, fable, or haiku, or semantic_decision.<leaf> where <leaf> is enabled, provider, model, timeout_ms, or consumers.<consumer> for domain-routing, fix-complexity, or orchestration-risk. It cannot remove credentials or values from other config sections.

Command flag

Flag	Default	Description
`--scope <scope>`	`user`	Select `user` or `project`.

Shared flags such as --json, --no-interactive, --quiet, --verbose, and --yes are described in CLI conventions.

Choose the scope

Scope	Config file	Result after removal
`user`	`$AGENTKIT_HOME/config.yaml`, or `~/.agentkit/config.yaml` by default	A project value can still override the preference; otherwise the built-in default applies.
`project`	`.agentkit/config.yaml` under the current working directory	The user value applies when present; otherwise the built-in default applies.

Unset a user preference:

ak config prefs unset hooks.simplify-gate
ak config prefs unset journal.auto
ak config prefs unset worktree.root
ak config prefs unset agent_models.cursor.sonnet
ak config prefs unset semantic_decision.enabled --scope user

Unset only the current project's preference:

ak config prefs unset hooks.simplify-gate --scope project
ak config prefs unset journal.auto --scope project
ak config prefs unset worktree.root --scope project
ak config prefs unset agent_models.cursor.sonnet --scope project
ak config prefs unset semantic_decision.enabled --scope project

The command does not search parent directories for a project config. Run it from the project directory whose .agentkit/config.yaml you intend to edit.

Files, backups, and schema boundary

When the selected key exists, AgentKit backs up the previous config under the AgentKit home, removes only that leaf, prunes a parent section such as hooks, journal, worktree, or semantic_decision that the removal leaves empty, and atomically rewrites the config. The success output reports the backup path. Other keys, comments, ordering, and the editor directive are preserved.

If the key or config file is already absent, the command succeeds as a no-op: it does not create, rewrite, or back up a file. There is no confirmation prompt, and the command does not read stdin or use the network.

unset validates the allowed key shape and must parse the YAML it edits, but it does not run a whole-document schema validation. Removing a leaf cannot introduce a new schema violation. Use ak config prefs validate to check the remaining document, especially when it was edited by hand.

Output for automation

With --json, success writes one shared success envelope to stdout with kind config.prefs.unset. The fields below are under data:

action: "unset"
key: string
scope: "user" or "project"
config_path: string
backup_path: string, omitted when no backup was created
found: boolean

Use found to distinguish a removal from an already-absent no-op. The command does not emit NDJSON.

JSON-mode failures, including flag-parse errors (exit 2), write the shared error envelope to stderr. Check the process exit status and do not parse stdout as success after a non-zero exit.

Exit behavior

Exit	Meaning	Safe next step
`0`	The key was removed, or it was already absent.	Inspect `found`, then resolve the effective value.
`1`	The key or scope was invalid, or the config/backup/write operation failed.	Correct the key or scope; restore the reported backup if a later verification fails.
`2`	The argument count or flags were invalid.	Correct the invocation.

--yes and --no-interactive do not change this policy because unset never prompts. --quiet does not suppress this command-specific stdout, and --verbose adds no command-specific diagnostics. There is no preview, dry-run, apply, or force mode.

Verify and recover

Verify the effective value and validate the remaining files:

ak config prefs resolve
ak config prefs validate

If the result is not what you intended, either set the explicit value again or restore the exact backup path printed by the command. Do not replace the whole AgentKit home: the backup covers only the previous config file.

CLI conventions

On this page