apps

beam apps manages installable Beam apps. Apps are sandboxed extensions loaded from the Beam app registry. Beam handles registry verification, local caching, permissions, wallet approvals, and execution.

Use this page for the generic app command surface. App-specific commands and examples live on each app detail page.

Lifecycle

$ beam apps install <app> [--version <version>] [--dry-run]
$ beam apps list
$ beam apps info <app>
$ beam apps permissions <app>
$ beam apps update [app]
$ beam apps remove <app> [--purge-data]

beam apps install <app> fetches the app metadata and artifact, verifies the registry signatures and SHA-256 digests, checks the minimum Beam version, then shows the permission summary before activating the app.

Use --dry-run to inspect the same install summary without writing the app to the local cache:

$ beam apps install <app> --dry-run

beam apps list shows installed apps. beam apps info <app> shows the active version and metadata. beam apps permissions <app> shows the app's declared network, chain, wallet, storage, and privacy capabilities.

beam apps update [app] updates one app when <app> is provided, or every installed app when it is omitted. If an update changes permissions, Beam shows a permission diff and asks before switching the active version.

beam apps remove <app> deactivates the app and keeps app-local data by default. Pass --purge-data to delete the app's local data as well:

$ beam apps remove <app> --purge-data

Execution

$ beam x <app> [app-command...]
$ beam apps run <app> [app-command...]

beam x <app> is the short form for running installed app commands. The explicit lifecycle form, beam apps run <app>, is equivalent and is useful in scripts that group app operations under one namespace.

App commands inherit Beam global flags before arguments are passed to the app:

$ beam --chain <chain> --from <wallet> x <app> <command> [args...]
$ beam --chain <chain> --from <wallet> apps run <app> <command> [args...]

Use beam x <app> --help to show the command reference exported by the installed app manifest.

Examples:

$ beam apps install uniswap
$ beam x uniswap swap USDC ETH 100 --chain base --from alice --prepare
$ beam apps install erc8004
$ beam x erc8004 support --chain base
$ beam x erc8004 register --uri https://agent.example/agent.json --chain base --from alice
$ beam x erc8004 set-wallet 1 alice --chain base --from alice

ERC-8004 agent identity management is a registry app, not a native beam agents command. Default registry addresses are included in the app manifest. Custom identity registries can be persisted with beam x erc8004 config set --identity-registry <address> or supplied per command with --identity-registry <address>.

Approvals

Wallet-affecting app commands are approved by Beam. Apps propose typed action plans; Beam validates the plan against the installed app's permissions before it signs or submits anything.

For non-interactive flows, prepare a continuation, inspect it, then explicitly approve and execute it:

$ beam --chain <chain> --from <wallet> x <app> <command> --prepare --format json
$ beam apps approvals show <approval-id>
$ beam apps approvals approve <approval-id> --execute

Approval commands:

$ beam apps approvals list
$ beam apps approvals show <approval-id>
$ beam apps approvals approve <approval-id> [--execute]
$ beam apps approvals reject <approval-id>

beam apps approvals list shows pending continuations. show renders the typed plan for review. approve marks the continuation approved; add --execute to run it immediately. reject closes a continuation without executing it.

Non-Interactive Safety

Use --no-prompt when an app command must fail instead of opening an interactive approval prompt:

$ beam --chain <chain> --from <wallet> x <app> <command> --no-prompt

--no-prompt fails closed for wallet-affecting commands unless the command is preparing a continuation or executing an already-approved continuation.

Prepared approvals are bound to the app id, app version, manifest digest, WASM digest, command, wallet, chain, action plan hash, and expiry. Updating the app or changing the command context invalidates stale continuations.