Getting started

Install the arca CLI, seal your first secret in the local age-encrypted vault, and run a command that uses it — without the value ever touching your terminal, a file, or an agent's context.

Install

The crates.io name arca belongs to an unrelated project — install from the repo:

cargo install --git https://github.com/9aia/arca arca

From a checkout of this repo: cargo xtask install builds and installs the release binary to ~/.cargo/bin/arca. For a lean binary without the TUI: cargo install --git https://github.com/9aia/arca arca --no-default-features.

Bootstrap

arca init

init stores your age identity where it's safest available and verifies the vault at ~/.local/share/arca/vault.age opens. It's idempotent — run it any time.

On a desktop session (GNOME Keyring, KeePassXC, KDE Wallet, macOS Keychain, Windows Credential Manager) the identity lands in the session keyring — it unlocks with login, no prompt. On headless boxes with no session store, init falls back to the ~/.config/arca/identity.txt keyfile (mode 0600) with a note saying so. arca init --with-file forces the keyfile; pinning ARCA_IDENTITY_FILE or [vaults.*].identity in config does the same — that's the headless/CI path.

Already have an identity.txt? arca init imports it into the keyring rather than orphaning it, and leaves the file as a backup you can delete when ready.

Seal a secret

Values never enter via CLI arguments — they would land in shell history and /proc. Pipe them instead:

printf '%s' "$STRIPE_KEY" | arca put arca://billing/stripe

Interactive humans get a hidden /dev/tty prompt instead of stdin. The value is encrypted to your identity and stored under the dev env (the default context).

Declare the surface

[secrets] in arca.toml bounds what run/env may inject — least privilege, no ambient vault dump:

[secrets]
STRIPE_KEY = "arca://billing/stripe"

Config search: ./arca.toml → ~/.config/arca/arca.toml (--config/$ARCA_CONFIG override). No file at all is fine — defaults are the local vault and the dev env.

Run with secrets

arca run -- 'curl -H "Authorization: Bearer $STRIPE_KEY" \
    https://api.stripe.com/v1/charges'

run resolves the declared refs, injects them as env vars into the child only, and exits with the child's code. One arg after -- runs via bash -c (shell syntax, as above); several args exec argv[0] directly with no shell. The value lives only in that process — agents never see it.

Check the setup

arca check

Validates the config, that the routed vaults decrypt, and that every [secrets] ref resolves — exit 1 on findings.

Agent self-discovery

arca manifest          # verbs, JSON shapes, env vars, audit contract (JSON)
arca schema            # JSON Schema for arca.toml
arca <verb> --help     # every verb, self-documenting

--json is honored on every verb; errors are {"error": "…"} on stderr with a non-zero exit. The arca skill teaches agents the verbs.

Where next

• Your first secret — a guided end-to-end in a throwaway HOME.
• Inject into a process — run modes, ad-hoc -s pairs, the eval "$(arca env)" human path.
• The threat model — what arca does and does not protect against.
• CLI reference — the full verb surface.