--- name: asiri description: "Use when an agent needs to operate Asiri CLI or Asiri-managed secrets: inspect secret metadata, run commands with scoped secrets, add or rotate operational secrets, manage human member access, push or pull encrypted records, configure service-account runtime access for CI or servers, or diagnose Asiri workspace/device state without exposing secret values. Focus on safe operational use first; use trust, recovery, rekey, revocation, member access, service-account setup, and remote policy changes only when explicitly requested." --- # Asiri Asiri is a secrets access layer. Treat it as the source of operational secrets and the local runtime that uses them without copying values into agent context. ## Core Rules - Never print, paste, log, summarize, or store secret values. - Prefer metadata-only checks: list workspaces, list secret names, check status, inspect audit. - Use exactly one `--workspace ` on hosted workspace-scoped commands. Human account/device sessions never select or switch an active CLI workspace. - Require an explicit canonical slug or alias for local and hosted secret listing. If a fresh offline vault has no workspace, guide the user to `asiri workspace create `. - Use exact workspace slugs and secret paths from the user or from `asiri workspace list` / `asiri list`. - Prefer `asiri env` or `asiri mount` over raw reads. - Use raw reads only when the user explicitly asks and the authenticated identity is allowed to read; redirect verification reads to `/dev/null`. - Treat `--label` as audit metadata only. A label never grants or denies access. `--agent` is a compatibility alias for `--label`. - Treat strict audit failures as hard stops. Do not retry, bypass, copy, or expose the secret through another path when Asiri says audit ack is required before release. - Stop before changing trust, device, recovery, rekey, or local key material unless the user explicitly asked for that repair. - If Asiri reports missing platform key material, keyring errors, duplicated devices, unknown trust, or recovery problems, report the state and ask before mutating anything. ## First Check Start routine work by discovering the visible workspaces: ```sh asiri workspace list ``` Do not run `asiri --version` or `asiri setup doctor` routinely. Use them only when troubleshooting installation, configuration, authentication, trust, key material, or unexpected CLI behavior. If the user named a workspace, confirm it is visible above, then inspect its secret metadata: ```sh asiri list --workspace ``` `asiri list --workspace ` is safe for normal inspection. It shows names, hashes, sync state, and write status. It does not print plaintext. ## Workspace Identity Treat the canonical slug as the immutable storage, encryption, binding, and sync identity. Treat an alias as a user-scoped CLI shortcut. Aliases may repeat across users but must be unique within one user's visible workspaces. Offline users can create any valid local workspace slug: ```sh asiri workspace create ``` Do not require local workspace creation before control-plane sign-in. Signup creates the verified-email personal workspace, which remains the account default and is listed first. Local workspace creation and sync never change that default. Continue to pass `--workspace` explicitly to every workspace-scoped command. On first push, Asiri assigns a canonical slug with an eight-character suffix, atomically re-encrypts the local workspace under it, and retains the former local slug as that user's alias unless the user already selected another local alias. If first sync fails during local migration, preserve the vault and key material and retry the same workspace; its stable local ID makes remote provisioning idempotent. Set or change the signed-in user's alias without changing canonical identity: ```sh asiri workspace alias set --workspace

``` Never infer workspace identity from an alias or rewrite an existing hosted canonical slug. New devices store canonical slugs and receive the signed-in user's aliases for CLI resolution. ## Use A Secret Prefer environment injection for tools that read environment variables: ```sh asiri env --workspace -- ``` For a group of direct child secrets under one scope: ```sh asiri env --workspace -- ``` Prefer temporary files for tools that read Docker-style secret files: ```sh asiri mount --workspace -- ``` Use an explicit audit label when the audit record should differ from the child command name. It never changes authorization: ```sh asiri env --workspace --label -- ``` Use argv substitution only as an escape hatch for tools that cannot read env vars or files: ```sh asiri run --workspace --label --unsafe-argv --token asiri:// ``` Envelope audit mode applies to every secret materialization path: raw read, env injection, mount, unsafe argv, and broker value requests. Buffered envelopes can release after local encrypted audit append and sync later. Strict envelopes must receive a matching control-plane ack before Asiri releases the value. If the device is offline or the ack is missing or malformed, report the block and stop. ## Add Or Track A Secret Use stdin or a value file. Do not put values in command arguments. From an environment variable: ```sh printf '%s' "$VALUE_FROM_EXISTING_ENV" | asiri add --workspace --stdin ``` From a file: ```sh asiri add --workspace --value-file ``` Both forms preserve exact bytes, including final newlines and empty input. Add a newline to stdin only when it is part of the secret. Binary secrets are safe for file mounts; environment injection cannot represent NUL bytes. After adding or rotating a secret that must be preserved remotely, push the narrowest target: ```sh asiri push --workspace --secret ``` Before a risky or broad push, use dry-run: ```sh asiri push --workspace --secret --dry-run ``` If a same-version remote record already exists and matches, push should skip it. If Asiri reports a conflict, do not overwrite blindly; inspect the local and remote metadata and ask. ## Runtime Access Local runtime access follows the authenticated user or service-account identity on a trusted device. Command, process, app, and agent labels do not authorize secret use. The former root-level label grant and deny commands were removed; use service-account policies when a fixed machine identity needs scoped access. Prefer env injection, mounts, or broker use so the value stays out of agent context. Use raw reads only when the user explicitly requests plaintext handling. Check recent activity without values: ```sh asiri audit tail --workspace --limit 20 ``` Audit mode is an envelope policy set by the workspace owner or a delegated admin. Do not change it unless the user explicitly asked for an audit-mode change. ## Human Member Access Use a trusted human device session created by `asiri login`. List members and current access without exposing values: ```sh asiri member list --workspace asiri member access list --workspace ``` Workspace owners can grant one active member access using an exact email or user ID: ```sh asiri member access grant --workspace --member --secret asiri member access grant --workspace --member --envelope asiri member access grant --workspace --member --envelope --include-descendants ``` Run the printed `asiri rewrap --workspace ` next step from a trusted device that can already decrypt the permitted secrets. Granting access never rewraps automatically. Revoke by the stable grant ID returned by `member access list`: ```sh asiri member access revoke --workspace --grant ``` Grant and revoke are remote, audited mutations and send transactional notifications. Revocation blocks future access through that grant. It does not erase decrypted or cached copies, and another active grant may still cover the same secrets. Service-account sessions cannot manage members. ## Pull, Push, And Rewrap Use pull when a trusted device needs encrypted remote records locally: ```sh asiri pull --workspace ``` Use push when local encrypted records should be tracked in the hosted workspace: ```sh asiri push --workspace ``` Use rewrap only when the user explicitly wants trusted devices or recovery recipients to receive wrapped access to existing encrypted records: ```sh asiri rewrap --workspace ``` ## Service Accounts, CI, And Servers Use service accounts for CI and servers instead of long-lived shared tokens. Service accounts are permission identities; trusted devices remain the decryption boundary. Only create, disable, or grant service accounts from a real authenticated user-device session: ```sh asiri service-account create --workspace --slug --name "" asiri service-account grant --workspace --service-account --scope --secret --inject-only ``` These are remote control-plane mutations. Run them only when the user explicitly asked to create, disable, or update service-account access. Service-account sessions cannot change control-plane state, add or rotate local secrets, remove local state, or edit local policy directly. They can pull encrypted records and allowed service policies for their granted workspace, then use those secrets through the local runtime. For service-account login, start a browser approval flow from the runtime device. A workspace owner or delegated service-account admin must approve it: ```sh export ASIRI_HOME="" asiri init --device gha-runner asiri service-account login --origin --workspace --service-account asiri whoami ``` After approval, `whoami` should show identity type `service account`, the service-account slug/name, workspace, device, and approving human. Runtime commands audit as the service account. Pull and injection still require the allowed secrets to be wrapped to the current trusted device: ```sh asiri pull --workspace asiri env --workspace -- ``` If pull reports that an allowed secret is not wrapped to this trusted device, ask the user to rewrap from a trusted device that can already decrypt it: ```sh asiri rewrap --workspace ``` Do not try to recover by storing decryption material in CI secrets unless the user explicitly chooses that operational tradeoff. ## Stop And Ask Stop before running any of these unless the user directly requested that exact operation: - `asiri init` on an existing install. - `asiri login --force`. - `asiri device trust --workspace `, `asiri device revoke --remote --workspace

`, or dashboard trust changes. - `asiri service-account create`, `asiri service-account disable`, or `asiri service-account grant`. - `asiri member access grant` or `asiri member access revoke`. - `asiri service-account login` when it would bind a new runtime device to a service account. - `asiri recovery setup --workspace `, `asiri recovery restore --workspace `, or recovery key handling. - `asiri rekey --workspace `. - Deleting or editing local Asiri state, keychain entries, or keyring material. - Recreating a workspace binding, migrating prefixes, or removing local secrets. When blocked by local key material or trust state, preserve the current state and explain the smallest safe next human action. ## Advanced Context Authenticated users and service accounts control authorization, and trusted device state is the runtime decryption boundary. Agent, app, process, and command names are audit labels only. Strict audit gives administrators visibility over Asiri-controlled secret release. It does not make a compromised trusted host safe, and it only applies after the device has synced the envelope policy. Human CLI login creates one account/device session. Every command names its target workspace explicitly and reuses that session. For CI or servers, prefer service accounts over long-lived shared tokens. A service account receives a browser-approved session scoped to one workspace, then uses the same local-runtime patterns: inject, mount, broker, pull, and audit. Service-account sessions cannot mutate secrets, policies, devices, members, billing, recovery, or service accounts. For suspected host compromise, revocation blocks future access but does not erase what the host may already have seen. Rotate the upstream secret after revocation.