3.0.0-beta.15). Features may change before the next stable release.Switch to stable →prefs
ak config prefs
Choose a preference lookup, validation, or bounded Hook, journal.auto, worktree root, agent model, or semantic_decision mutation while preserving scope, defaults, secrets, and backup boundaries.
Use ak config prefs to discover the commands that resolve or change
AgentKit's authored preference values. The group command itself prints help; it
does not read or write a config file.
Usage
ak config prefsThe command has no command-specific flags. Shared flags are described in
CLI conventions, but --json does not turn group help
into a preference payload.
Choose a preference command
| Goal | Command | Effect |
|---|---|---|
| See effective authored values | ak config prefs resolve | Reads user and current-project config, then deep-merges project over user. |
| Check config syntax and schema | ak config prefs validate | Reads existing user/project files, or one explicit --file; writes nothing. |
| Pin one Hook toggle, the automatic journal step, the default worktree root, one runtime capability-tier agent model, or one semantic decision setting | ak config prefs set <key> <value> | Backs up an existing selected config, then atomically writes one hooks.<name> boolean, the exact journal.auto leaf, the exact worktree.root path, one agent_models.<runtime>.<tier> model ID, or one semantic_decision.* leaf. |
Stop pinning one Hook toggle, journal.auto, worktree.root, an agent model, or a semantic decision setting | ak config prefs unset <key> | Removes one selected-scope hooks.<name>, journal.auto, worktree.root, agent_models.<runtime>.<tier>, or semantic_decision.* leaf when present, with a backup before rewrite. |
These commands do not edit provider keys, API tokens, update settings, or other
setup-owned sections. Semantic decision credentials come from the
process environment or $AGENTKIT_HOME/.env, never from config. See
providers and credentials.
Understand scope and precedence
The candidate files are:
- user scope:
~/.agentkit/config.yaml, or$AGENTKIT_HOME/config.yaml; - project scope:
.agentkit/config.yamlunder the command's current working directory.
Resolve deep-merges project values over user values. A project mapping can
override one nested key while preserving user values beside it. These are
authored values only: missing keys are not filled with binary defaults. Each
Kit Hook applies its own built-in default when a value is absent, and
journal.auto defaults to true.
set and unset default to user scope; pass --scope project to select the
current project's file. Scope is based on the process working directory, not a
registered project chosen elsewhere.
semantic_decision is an exception to project-over-user precedence. Only user
scope can grant provider consent or choose provider settings; project scope can
only set semantic_decision.enabled or a
semantic_decision.consumers.<consumer> entry to false. See
ak eval decision for how the grant is resolved and
what it sends.
Privacy and output boundary
Resolve allowlists preference sections and converts their field names to the
legacy camel-case spelling consumed by Kit Hooks. Setup credential sections,
including keys and api, are excluded. The extensions section is passed
through verbatim, however, so treat preference output as potentially sensitive
user-authored data and review it before sharing logs.
set, unset, and validate write the shared schema_version/kind/data
success envelope. resolve keeps its raw preference document because Kit Hooks
parse it directly. Bare ak config prefs
prints ordinary Cobra help to stdout and normally exits 0.
With --json, a failure in these preference commands, including a flag-parse
error (exit 2), writes the shared error envelope to stderr. Use the process
exit status and validate success output before consuming it.
An unknown subcommand or extra positional token instead follows the generic
runtime error path and exits 1.
Write and recovery boundary
Set/unset writes preserve unmodelled YAML sections, comments, key order, and
the schema editor directive. Replacement uses a sibling temporary file and
mode 0600. An existing target is copied first under
~/.agentkit/backups/config/; the success output reports the exact backup path.
Backups are individual config-file copies, not a transaction across user and project scopes. Avoid concurrent config writers. To recover, stop other writers, inspect the reported backup, and copy that file back to the reported config path; no automatic preference rollback command is provided.