AgentKit
DocsKitsCLI ReferenceDesktop App
BetaYou are reading docs for the beta channel (3.2.0-beta.10). Features may change before the next stable release.Switch to stable →

sync

ak secrets sync now

Run one sync cycle now, or keep syncing with --watch

Use ak secrets sync now for the operation described below. The command help records its arguments, effects, and options.

Command contract

Run one sync cycle now, or keep syncing with --watch

Synopsis

Pull remote changes, push local changes, and record a signed checkpoint. A large push is paced under the vault server's per-device rate limit; if the server still answers rate limited, the command waits for its Retry-After (announced on stderr, up to 15 minutes in all) and goes on with the next cycle, so a bulk import finishes in one run. With --watch, keep syncing until interrupted: local changes sync within seconds, and the server is polled every --interval (1 minute by default) while this device saw activity in the last 10 minutes (a local change, a cycle that pulled or pushed something, a relay call), otherwise every 5 minutes, so a change made on another device arrives within 5 minutes even when idle. Each wait varies by up to 10% so devices do not poll in step. When nothing changed, the server answers the change-log read without sending or re-reading it. An unreachable server is retried with backoff, and a token refusal right after a vault server restart is retried for about a minute. --watch reports other problems and keeps going; it stops on an integrity alarm, an authentication failure, sync being turned off, a moved store, a local storage failure or an unavailable passphrase.

--relay (with --watch) also keeps a connection open to the vault server so the AI tools you connected to your vault over remote MCP can reach this device: they search, list and describe secrets, set and delete them, request access, and run a program under an exec grant already pinned here. Values never leave the device, nothing prompts, and a call no grant covers is filed for ak secrets approve. Each call is recorded in the vault's encrypted audit log (tool, client and outcome, never a value). It also applies the writes those tools queued while no device was online. A remote set or delete is refused as a queued one is (a policy item, a secret that does not sync, a name two items share, a device that is not a human owner or editor device, any write while a rekey is pending), a remote write to a secret with a local edit or a new local secret not yet synced answers conflict until the next cycle takes it up, and remote deletes past the mass-delete guard are refused unless --allow-mass-delete is set. A relay problem only changes the relay status line; the sync loop goes on. A compromised vault server could forge the writes a relay applies, so an AI agent may not start it: --relay run by an agent is refused, while plain sync now stays open to agents.

Effects: Writes pulled changes into this device's secrets store and uploads encrypted local changes. With --relay, remote calls may write or delete secrets, file approval requests, and start programs an exec grant allows.

Output: With --json, NDJSON: one compact secrets.sync.now envelope per line, one line per cycle (a single line without --watch), and with --relay one secrets.sync.relay envelope per relay status change. Without --json a relay status prints as relay: connected, relay: reconnecting or relay: stopped(<reason>).

Exit status: 0 synced (or --watch was interrupted) 1 the server refused (quota, unsupported protocol) 2 invalid flags, or the store moved since enable 5 local storage failure 6 refused: an AI agent is running --relay 7 the file-backend passphrase is unavailable 10 sync is not enabled on this device 11 the vault server is unavailable, or still rate limiting after 15 minutes of waiting; retry 12 synced, but something needs attention (see the output) 13 integrity alarm; sync halted 14 not logged in, token refused, or this device was removed

ak secrets sync now [flags]

Examples

  ak secrets sync now
  ak secrets sync now --watch --relay
  ak secrets sync now --allow-mass-delete

Options

      --allow-mass-delete      Push deletions even when they exceed the mass-delete guard
      --backend string         Storage backend: keychain (default), file (age-encrypted vault), or memory (dev/test; values and its index are throwaway)
  -h, --help                   help for now
      --interval duration      How often --watch polls the server while active (5s to 5m); an idle device polls every 5m (default 1m0s)
      --json                   Emit machine-readable JSON (implies --no-interactive)
      --no-interactive         Disable interactive prompts (CI-safe)
  -q, --quiet                  Suppress non-error output on stderr
      --relay                  With --watch, also answer remote MCP calls from your AI tools on this device
      --unlock-with-recovery   Open the file backend's vault with a recovery private key and set a new passphrase
  -V, --verbose                Extra diagnostic output on stderr (loses to --quiet)
      --wait-lock duration     How long to wait for another sync cycle to finish (default 30s)
      --watch                  Keep syncing until interrupted
  -y, --yes                    Assume yes for all prompts

SEE ALSO

  • ak secrets sync - Sync secrets across your machines with end-to-end encryption (preview)