Issue a capability token

tovio agent new refactor-bot --model anthropic:claude-opus-4-8 --task "extract the parser module"

Issues a scoped token and prints its id (cap_…), the agent DID, the scope it received, and the expiry window. The name forms both the agent's DID did:tovio:agent/<name> and its lane scope agent/<name>/**.

The flags

tovio agent new <name> --model <id> --task <text> --expires-in 2 --can-delegate

Notice what is not here: there are no path, lane, operation or clearance flags. Scope is not something you dial in at issuance — see Scope a token properly for the two mechanisms that genuinely narrow a token.

It also provisions a key

agent new creates a signing-only identity for the agent in your OS keychain and registers it under your human identity. That key is what signs sub-tokens and the agent's own audit entries. Re-running agent new for the same name deliberately reuses the existing key rather than generating a fresh one, so anything the old key signed stays verifiable — but it does issue a new capability token.

Managing them

tovio agent listtovio agent show <token-id>tovio agent token <token-id>tovio agent renew <token-id> --expires-in 8tovio agent revoke <token-id>

agent list marks each token active, expired or revoked and shows its scope and expiry. Add --json for the full record, including the excluded paths.

Finding the task id

Each token also carries a generated task id, and that is what tovio log --task-id and tovio audit graph task:<id> take. It is not printed at issuance — read it off an agent commit:

tovio log --entity agent --json

Renew mints a new token

agent renew is a deliberate re-issue, never an extension. It produces a new token id, links it to the previous one in the audit log, and hands the agent a different credential — so the old id stops being the answer to "which token did this?". A revoked token cannot be renewed at all.

Handling the token material

agent token prints the hex-encoded signed token object. It carries no key material — nothing decrypts with it, and it is a public, signed object — but presenting it is how a client opens a session. Treat it as a credential: pipe it into the client rather than pasting it into a chat, a log or a support ticket.

Its blast radius is bounded in three ways at once: by its own path and operation scope, by its expiry, and by agent revoke, which ends it immediately.