3.1.0-beta.10). Features may change before the next stable release.Switch to stable →prefs
ak config prefs unset
Remove one scoped hook, journal.auto, worktree.root, skill_routing.cloud_discovery, 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, the
skill_routing.cloud_discovery leaf, the updates.channel leaf, one agent_models 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.
skill_routing.cloud_discovery is likewise a consent grant that only the user
config can give. Removing the user value returns it to disabled, and removing a
project value restores the user policy for that project.
updates.channel is user scope only. Removing it deletes the stored binary
channel, so ak self-update and ak versions fall back to the channel of the
running build, then stable. --scope project is rejected.
To remove a preview feature preference, use ak config prefs unset features.<name> in
user scope. An environment override still applies. Run ak features list to see the
resulting source and state.
Usage
ak config prefs unset <key>The command requires exactly one positional argument. The key must be one of:
hooks.<name>—<name>is a lowercase kebab-case Hook script name.journal.auto,worktree.root,skill_routing.cloud_discovery, orupdates.channel— the exact literals.updates.channelaccepts only the user scope.agent_models.<runtime>.<tier>,agent_models.<runtime>.agents.<agent>.<field>, oragent_models.omp.roles.<role>.<field>— the same keysak config prefs setaccepts, onclaude-code,codex,cursor,omp, orpi.agent_models.<runtime>or any key under it for a capability-gated runtime (grokordsh).setnever writes these, but a hand-edited config can hold them, andunsetclears the refresh warning.semantic_decision.<leaf>—<leaf>isenabled,provider,model,timeout_ms, orconsumers.<consumer>fordomain-routing,fix-complexity,orchestration-risk,skill-routing-eval,review-triage,workflow-controller,ui-regression,test-impact, ore2e-classification.
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 skill_routing.cloud_discovery
ak config prefs unset updates.channel
ak config prefs unset agent_models.cursor.sonnet
ak config prefs unset agent_models.claude-code.agents.kongming.model
ak config prefs unset agent_models.grok
ak config prefs unset semantic_decision.enabled --scope userUnset 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 skill_routing.cloud_discovery --scope project
ak config prefs unset agent_models.cursor.sonnet --scope project
ak config prefs unset agent_models.grok --scope project
ak config prefs unset semantic_decision.enabled --scope projectThe 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, skill_routing, 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: booleanUse 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 validateIf 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.
Related commands
ak config prefs set
Set one bounded Hook boolean, the journal.auto preference, the worktree.root default, one runtime capability-tier agent model, or one semantic_decision setting with exact scope, schema, backup, atomic-write, output, and manual-recovery behavior.
ak config prefs validate
Validate AgentKit YAML against the schema embedded in the CLI and use findings safely in local or CI checks.