ak secrets grant

Cho phép một binary agent đã lấy fingerprint đọc một bí mật.

Dùng ak secrets grant với đối số và tùy chọn dưới đây. Phần help nguyên bản giữ nguyên thuật ngữ, cú pháp, tác động và điều kiện thực thi của CLI để đối chiếu chính xác.

Contract và help của lệnh

Let a fingerprinted agent binary read a secret

Synopsis

Record that one agent binary may read one secret. A grant is keyed by four fields — secret, project, binary fingerprint, and purpose — and all four must match for it to apply; an empty --purpose is a literal value, not a wildcard. Only the fingerprint carries authority: it is the hash of the caller's executable file, not the adapter's name and not whether it was pinned.

--project defaults to the AK project containing the current directory; an explicit path resolves to the root of the AK project that contains it, and "default" names the shared slot. Two git worktrees of one repository are two projects, so grants do not carry between them, and any directory outside an AK project falls into the shared "default" slot — there the scope is effectively secret, binary, and purpose alone for every such directory on the machine.

An allow expires after 24h unless --ttl or --persist says otherwise. --block records a refusal that outranks every allow on the same scope and never expires unless --ttl asks it to; clearing it takes an explicit ak secrets revoke.

A grant trusts the agent's model with the plaintext: the model can run the same binary that resolves ${secret:NAME}, so it can read any value it is granted. Grant only what that agent should hold, and rotate a secret it no longer needs.

--allow-host restricts an allow to specific destinations: a WebFetch.url that resolves a secret reference must target one of the given hosts (or host:port), matched exactly and case-insensitively after normalization — a default :443 or :80 port and one trailing dot are stripped, and an internationalized name is converted to its ASCII form — with no wildcards. Only the port is normalized this way, not the scheme: an http:// URL to a host matches a :443 (or port-less) list entry exactly as an https:// URL does. It is repeatable and comma-separated. The check runs inside ak secrets resolve itself: it governs what the inject hook substitutes and what resolve releases when it is told the destination, but it does not follow the caller — nothing stops a model from invoking ak secrets resolve itself with a self-asserted --dest-host. The hook sends no --dest-host for a Bash.command reference (a shell command line names no single destination to check), a WebFetch.url it could not parse a host out of, or one where a reference sits inside the host, port, or userinfo itself; an unrestricted grant still resolves and substitutes every one of these exactly as it did before this flag existed, while a restricted grant refuses all of them outright, never raised for approval, even under AGENTKIT_SECRETS_INJECT_AUTO_ALLOW. A grant recorded with no --allow-host places no destination restriction, matching today's behavior. Granting a scope that already carries an --allow-host list — including approving a pending request for it, allow-once included — never drops hosts from it on its own; only an --allow-host on the new grant replaces the list. Revoke the scope first (ak secrets revoke) to lift a restriction entirely. --allow-host is rejected on --block: a block already refuses every destination.

Effects: Writes one allow or block row into the grants file under AGENTKIT_HOME, replacing any earlier row with the same four-field scope and state. An allow and a block on one scope are kept side by side, and the block wins. Recording an allow also compacts grants whose expiry has passed. Stored secret values are not read or changed.

Exit status: 0 success 2 invalid flags, fingerprint, ttl, allow-host, or grant 5 the grant file could not be read or written 6 an agent adapter is above this process; an agent may not grant itself access

ak secrets grant <ref> [flags]

Examples

  ak secrets grant ${REF} --agent sha256:${HASH}              # 24h allow
  ak secrets grant ${REF} --agent sha256:${HASH} --persist    # no expiry
  ak secrets grant ${REF} --agent sha256:${HASH} --block      # refuse, outranks allows, no expiry
  ak secrets grant ${REF} --agent sha256:${HASH} --allow-host api.example.com  # only that host

Options

      --agent string         Agent binary fingerprint, sha256:<64 hex> (required)
      --agent-label string   Display name for the fingerprint; cosmetic, never matched against
      --allow-host strings   Destination host (or host:port) this allow may reach; repeatable or comma-separated, no wildcards, rejected on --block
      --block                Record a block instead of an allow
  -h, --help                 help for grant
      --json                 Emit machine-readable JSON (implies --no-interactive)
      --no-interactive       Disable interactive prompts (CI-safe)
      --persist              Record a grant with no expiry
      --project string       Project slot; defaults to the AK project containing the current directory
      --purpose string       Free-text purpose label; matched literally
  -q, --quiet                Suppress non-error output on stderr
      --ttl string           How long the grant lives, e.g. 12h, 30d, 2w (allows default to 24h; blocks never expire)
  -V, --verbose              Extra diagnostic output on stderr (loses to --quiet)
  -y, --yes                  Assume yes for all prompts

SEE ALSO

• ak secrets - Manage named secret values (API keys, tokens)