ak migrate prefs

Use ak migrate prefs when legacy .ck.json settings remain, including after kit content has already moved. It migrates preferences only; it does not move or install kits.

Usage

ak migrate prefs [flags]

The documented command has no positional arguments. The current implementation ignores extra positional tokens; do not rely on that behavior.

Options

Applying requires both --dry-run=false and --yes:

ak migrate prefs --dry-run=false --yes

There is no prompt or stdin read. --json, --no-interactive, and non-TTY stdin do not bypass the explicit --yes requirement. Shared output flags are described in CLI conventions.

Source and destination authority

The command checks up to two local files:

AGENTKIT_CLAUDE_HOME can change the Claude home, and AGENTKIT_HOME can change the AgentKit home. Project scope always comes from the current working directory. The command performs no network, registry, authentication, entitlement, provider, process-launch, or cache operation.

Understand merge precedence

Each readable legacy file becomes a plan of leaf-level actions:

• a value missing from AgentKit is marked migrate;
• a value already set in config.yaml, including explicit null, is keep_existing and wins;
• recognized top-level legacy sections map to AgentKit section names;
• unrecognized top-level keys are preserved under extensions;
• credential-like project values are omit_secret and never written to the project config.

User-scope credentials are not omitted. If a legacy user preference contains a key whose name includes passphrase, password, secret, token, apikey, or api_key, applying can copy that value into the user config.yaml. The writer sets the resulting file mode to 0600.

The legacy .ck.json files are always left in place. The migration is safe to rerun because existing AgentKit values take precedence.

Writes, journal, and rollback

Dry-run reads both scopes and writes nothing. Apply creates missing config directories with user-only permissions and replaces each config atomically through a sibling temporary file.

Before the first config write, AgentKit records all destination pre-images in one migration rollback journal. If any apply step fails, the journal remains so ak migrate rollback can restore the pre-apply files. After every write succeeds, the journal is discarded; a completed preference migration cannot be undone by ak migrate rollback.

Human and JSON output

Human stdout reports each source and destination, counts for migrate and keep_existing, omitted credential counts, and unreadable sources. No source is a clean nothing to migrate result.

One unreadable or malformed .ck.json is skipped while other readable scopes continue. Even when every discovered source is unreadable, the command reports the skips and exits 0; treat skipped as part of the result, not as a fatal error signal.

JSON stdout uses a command-specific map, not the shared kind/data envelope:

{
  "schema_version": 1,
  "prefs": {
    "schema_version": 1,
    "status": "planned",
    "plans": [
      {
        "schema_version": 1,
        "scope": "global",
        "source_path": "/home/you/.claude/.ck.json",
        "config_path": "/home/you/.agentkit/config.yaml",
        "entries": [
          {"legacy_path":"statusline","config_path":"statusline","action":"migrate"}
        ]
      }
    ]
  }
}

Possible status values are no_sources, planned, and completed. Plans do not include preference values, but human and JSON reports expose local paths; redact those paths before sharing logs. Command errors remain plain text rather than the shared JSON error envelope.

Exit status

Related commands

• Complete migration command facts
• Migrate from ClaudeKit
• Configuration troubleshooting