Commands and configuration

Run aomi --help for the installed top-level surface and aomi <command> --help for exact options. This page describes npm latest (0.7.6 on September 22, 2026) and calls out the additional commands in merged 0.9.4 source.

Agent commands

chat

Send one message and exit:

aomi chat "compare ETH lending rates" --new-session
aomi chat "use the Aave App" --mode direct --app aave
aomi chat "show tool activity" --verbose

The message is positional. --verbose or -v streams Agent messages, tool calls, and events while the turn runs. Without it, the command prints the final response.

session

Command	Purpose
`aomi session list`	List local session records.
`aomi session new`	Create a session and make it active.
`aomi session resume <id>`	Resume `session-N` or a backend session ID.
`aomi session delete <id>`	Delete one local session record.
`aomi session status`	Fetch the active Agent session state.
`aomi session log`	Show conversation history.
`aomi session events`	Show system events.
`aomi session interrupt`	Interrupt the active Agent turn.
`aomi session close`	Clear the active local session pointer.

Closing or deleting a local record does not turn a session ID into an authentication boundary. Backend session ownership still comes from the guest or account credential.

model

Command	Purpose
`aomi model list`	List models exposed by the selected environment.
`aomi model set <rig>`	Set and persist a model for the active session.
`aomi model current`	Read the locally selected model.

app

The published 0.7.6 package provides:

Command	Purpose
`aomi app list`	List Apps available through the selected environment.
`aomi app current`	Show the current routing mode and Direct App selection.

Select an App with --app, --application-id, or /app in the REPL. There is no aomi app use command. Merged client 0.9.4 source adds account-owned App installation and credentials:

Command	Purpose
`aomi app list`	List account Apps and installation state.
`aomi app available`	List executable Pipeline Apps.
`aomi app add <app>`	Install an account App by exact name or Application ID.
`aomi app remove <app>`	Remove an installed account App.
`aomi app credentials status <app>`	Show declared slots and whether each is configured.
`aomi app credentials set <app> <name>`	Save a missing credential from a hidden prompt or stdin.
`aomi app credentials replace <app> <name>`	Replace an existing credential.
`aomi app credentials remove <app> <name>`	Remove one saved credential.

The account App commands require client 0.9.4 or newer and matching Account API support. They are not in npm latest 0.7.6. Credential values are never command-line arguments: an interactive terminal reads without echo, and a non-interactive process reads one value from stdin.

Persistent App credentials, temporary session secrets, and model-provider BYOK keys are separate stores. See Apps and authentication.

Wallet and account commands

tx

The command group is named tx, but its records are Agent Actions:

Command	Purpose
`aomi tx list`	Fetch Actions for the active Agent session.
`aomi tx simulate <id...>`	Simulate selected pending EVM execution Actions as one batch.
`aomi tx export <id...>`	Export pending EVM execution Actions for an external wallet.
`aomi tx sign <id...>`	Execute selected pending Actions with configured wallet capabilities.

tx export supports --format eip5792 (default), moss, and metamask. See Transactions and signing.

chain

Command	Purpose
`aomi chain list`	List built-in EVM chain metadata.
`aomi chain set <id>`	Persist the active EVM chain ID.
`aomi chain current`	Show the active EVM chain ID.

Current source includes Ethereum (1), Optimism (10), Polygon (137), Monad (143), MegaETH (4326), Robinhood Chain (4663), Arc (5042), Base (8453), Monad Testnet (10143), Arbitrum (42161), Linea Sepolia (59141), Linea (59144), Base Sepolia (84532), Sepolia (11155111), Arc Testnet (5042002), and local Anvil (31337). Your installed version can have an older table; aomi chain list is authoritative for that binary.

wallet

Command	Purpose
`aomi wallet set <hex-key>`	Persist an EVM signer and derived address.
`aomi wallet set --evm <hex-key>`	Explicit form of the EVM command.
`aomi wallet set --solana <base58-key> [--cluster <name>]`	Persist an SVM signer and cluster.
`aomi wallet current`	Show configured EVM and SVM wallets.
`aomi wallet whoami`	Show the authenticated backend account.

wallet set writes signing keys to the owner-only local session file. Use a per-command signing flag or environment variable if you do not want to persist a key.

account

Command	Purpose
`aomi account login`	Sign in with OAuth device authorization.
`aomi account login --wallet`	Sign in with SIWE and the configured EVM signer.
`aomi account login --solana`	Sign in with SIWS and the configured SVM signer.
`aomi account login --provider privy\|para`	Use a supported browser provider flow.
`aomi account whoami`	Show the authenticated account.
`aomi account links`	List login methods and linked wallets.
`aomi account link`	Link an EVM wallet by default.
`aomi account link --solana`	Link an SVM wallet.
`aomi account link --provider privy\|para`	Link a provider identity.
`aomi account unlink <id> --yes`	Remove a linked identity or wallet.
`aomi account rename <id> --label <text>`	Rename a linked identity or wallet.
`aomi account update`	Set `--display-name` and/or `--avatar-url`.
`aomi account delete --yes`	Delete the account.
`aomi account sessions`	List local CLI records used for account switching.
`aomi account switch <id>`	Switch the active local CLI record.
`aomi account logout`, `aomi logout`	Revoke or clear login state and saved signing keys.

--wallet, --solana, and --provider are mutually exclusive on login and link commands. Account credits are nested under account credits:

Command	Purpose
`aomi account credits show [--limit N] [--before id]`	Show included allowance, Credit Bank balance, and activity.
`aomi account credits top-up <credits> --idempotency-key <key>`	Buy durable credits with the configured EVM wallet.

Reuse the same idempotency key only when retrying the same top-up.

Pipeline commands

Pipeline provides discovery and a stateless Build lifecycle:

Command	Purpose
`aomi pipeline read [path]`	Read a Pipeline resource.
`aomi pipeline apps [-q text] [--limit N]`	List Apps.
`aomi pipeline app <name>`	Describe one App.
`aomi pipeline skills [-q text] [--limit N]`	List skills.
`aomi pipeline skill <name> [--instructions]`	Describe a skill or print its instructions.
`aomi pipeline operations --app <app>`	List App operations.
`aomi pipeline operations --skill <skill>`	List skill operations.
`aomi pipeline operation <name> --app <app>`	Read an operation schema.
`aomi pipeline invoke <name> --app <app> --arguments <input>`	Validate and invoke one operation.
`aomi pipeline build <name> --app <app> --arguments <input>`	Build and simulate one operation.
`aomi pipeline evm build\|stage\|simulate\|commit <input>`	Run an explicit EVM Build transition.
`aomi pipeline svm build\|stage\|simulate\|commit <input>`	Run an explicit SVM Build transition.

--arguments and lifecycle <input> accept an inline JSON object, a path, @path, or - for stdin. Supply --idempotency-key to pipeline invoke or a raw commit when you need to retry the same mutation. Pipeline Build values are opaque transition inputs. Pass the complete staged value to simulate, and the complete simulated value to commit. Do not reconstruct them from displayed fields.

Configuration and deployment commands

Command	Purpose
`aomi config current`	Show the persisted backend URL.
`aomi config set-backend <url>`	Persist a backend URL.
`aomi secret list`	List temporary secret handles for the active session.
`aomi secret add NAME=value [...]`	Send temporary values to the backend secret service.
`aomi secret clear`	Clear temporary secrets for the active session.

There is no top-level --secret flag. Shell history can retain NAME=value; prefer a private shell input mechanism for sensitive values. The client bundle also exposes aomi deploy, aomi deploy status, and aomi deploy activate for Project deployment. Use aomi deploy --help for its Project ID, activation token, branch, commit, and preflight options. Builder documentation remains canonical for authoring and release workflows.

Global flags and environment variables

Flags override environment variables. Most global flags work on Agent, account, and wallet subcommands. Pipeline and deploy commands intentionally expose narrower sets; use their command help.

Flag	Environment variable	Purpose
`--backend-url <url>`	`AOMI_BACKEND_URL`	Aomi API or BFF origin.
`--api-key <key>`	`AOMI_API_KEY`	App access key, sent as `Aomi-App-Key`.
`--account-bearer <token>`	`AOMI_ACCOUNT_BEARER`	Pre-acquired account credential. Prefer `aomi account login` for managed grants.
`--json`	—	Print JSON where the command supports it.
`--verbose`	—	Print diagnostics, including local state paths.
`--mode auto\|direct`	`AOMI_AGENT_MODE`	Agent routing mode.
`--app <name>`	`AOMI_APP`	Direct App name; implies Direct mode.
`--application-id <id>`	`AOMI_APPLICATION_ID`	Canonical hosted Application ID; implies Direct mode.
`--platform <name>`	`AOMI_APP_PLATFORM`	Platform selector used with hosted App discovery.
`--model <rig>`	`AOMI_MODEL`	Model preference for the active session.
`--new-session`	—	Create a new active session for this command.
`--chain <id>`	`AOMI_CHAIN_ID`	EVM chain context.
`--public-key <address>`	`AOMI_PUBLIC_KEY`	Exact EVM address for wallet context.
`--solana-public-key <address>`	—	Exact SVM address for wallet context.
`--private-key <hex>`	`PRIVATE_KEY`	Transient EVM signer.
`--solana-private-key <key>`	`SOLANA_PRIVATE_KEY`	Transient SVM signer.
`--cluster <name>`	`AOMI_SOLANA_CLUSTER`	`mainnet-beta`, `devnet`, `testnet`, or the matching `solana:*` value.
`--rpc-url <url>`	`CHAIN_RPC_URL`	RPC used by wallet execution.
`--payment-method coinbase`	`AOMI_PAYMENT_METHOD`	Paid Agent or Pipeline settlement rail.
`--inference-funding user_byok`	`AOMI_INFERENCE_FUNDING`	Use the account’s saved model-provider BYOK key.
—	`AOMI_STATE_DIR`	Local state root; defaults to `~/.aomi`.

Root mode also accepts -p, --prompt, --show-tool, and --provider-key <provider:key>. On aomi chat, -v means --verbose; use aomi --version for the package version. If --public-key and --private-key are both present, the CLI requires them to describe the same EVM account. The same consistency check applies to --solana-public-key and a configured SVM signer.

Local state

The CLI stores sessions under AOMI_STATE_DIR or ~/.aomi:

sessions/session-N.json stores one local session record with file mode 0600.
active-session.txt selects the active local record.
The state directory is created with mode 0700 where the operating system supports it.

A local record can contain the backend session ID, routing target, model, App key, guest or account credentials, OAuth refresh grants, wallet addresses, optional saved signing keys, chain context, and temporary secret handles. Current CLI state does not store a second pending/signed transaction ledger. aomi tx list fetches durable Actions from the Agent session.

Treat the state directory as a credential store. A saved wallet key, account bearer, or OAuth refresh grant can authorize sensitive work. Do not commit, print, or copy session files into logs.

Use --verbose to print the active state path for commands that support it.

Try Aomi

Integrate Aomi

Concepts

Security

Payments

Multi-chain Support

Case Studies

Resources

Commands and configuration

Agent commands

chat

session

model

app

Wallet and account commands

tx

chain

wallet

account

Pipeline commands

Configuration and deployment commands

Global flags and environment variables

Local state

​Agent commands

​chat

​session

​model

​app

​Wallet and account commands

​tx

​chain

​wallet

​account

​Pipeline commands

​Configuration and deployment commands

​Global flags and environment variables

​Local state

Agent commands

chat

session

model

app

Wallet and account commands

tx

chain

wallet

account

Pipeline commands

Configuration and deployment commands

Global flags and environment variables

Local state