Client CLI - Aomi

The aomi command ships inside the @aomi-labs/client npm package. You use it to chat with an Aomi backend, keep a session across runs, inspect wallet requests, sign and submit transactions, and manage per session secrets.

This is the client CLI. It talks to a running Aomi backend. It is not the builder toolchain.If you are building and shipping an Agentic Application, you want the Rust SDK tools aomi-build, aomi-run, and aomi-git instead. See the builder toolchain for those. This page covers only the npm aomi client.

The package is published as @aomi-labs/client and registers one binary named aomi.

Install

Run once with npx
Global
pnpm

npx @aomi-labs/client --version
npx @aomi-labs/client --help

npm install -g @aomi-labs/client
aomi --version

pnpm add @aomi-labs/client
pnpm exec aomi --version

Examples below use aomi for brevity. To run a command once without installing, prefix it with npx @aomi-labs/client.

Two ways to run it

The root command has two modes plus a set of noun verb subcommands.

Interactive REPL

Run aomi with no arguments to open a prompt. Type messages, or use slash commands like /app, /model, and /key. Requires a TTY.

Single message and scripting

Run aomi --prompt "..." to send a single message and exit, or use a subcommand such as aomi tx sign or aomi secret add for non interactive flows.

Interactive REPL

aomi

This opens a prompt. Anything that is not a slash command is sent to the agent as a message. The REPL needs a real terminal. In a non TTY environment (a pipe or CI job), use --prompt instead. Slash commands available inside the REPL:

Command	What it does
`/heap`	Show the REPL help
`/app <name>`	Switch the active app
`/model <rig>`	Set the active backend model
`/model list`	Show available models
`/model show`	Show the current model
`/key <provider:key>`	Save a BYOK provider key
`/key show`	Show BYOK provider key status
`/key clear`	Clear all BYOK provider keys
`:exit` (or `:quit`)	Quit the CLI

Single prompt

aomi --prompt "swap 1 ETH for USDC"
aomi -p "what is the price of ETH?"
aomi --prompt "hello" --show-tool

Pass --show-tool to print tool output while running in prompt or REPL mode. You can save a bring your own key provider key before the prompt runs:

aomi --provider-key anthropic:sk-ant-... --prompt "hello"

Commands

chat

Send one message and print the response, then exit.

aomi chat "swap 1 ETH for USDC"
aomi chat "swap 1 ETH for USDC" --model claude-sonnet-4
aomi chat "swap 1 ETH" --verbose

The message is a positional argument. --verbose (or -v) streams agent responses, tool calls, and events live. Without it, only the final agent message prints.

tx

Manage the transactions the backend hands back as wallet requests.

Command	What it does
`aomi tx list`	List pending and signed transactions
`aomi tx simulate [txIds...]`	Simulate a batch of pending transactions
`aomi tx sign [txIds...]`	Sign and submit pending transactions

tx simulate and tx sign take zero or more transaction IDs as positional arguments. See Transaction flow and Signing modes below.

session

The CLI is not a long running process. Each command starts, runs, and exits. Session state lives locally between runs so the next command continues the same conversation.

Command	What it does
`aomi session list`	List local sessions with metadata
`aomi session new`	Start a fresh session and make it active
`aomi session resume <id>`	Resume a local session by ID or `session-N`
`aomi session delete <id>`	Delete a local session by ID or `session-N`
`aomi session status`	Show current session state
`aomi session log`	Show conversation history
`aomi session events`	List system events
`aomi session close`	Close the current session

aomi session list
aomi session resume session-2
aomi session log
aomi session status
aomi session close

model

Discover and switch backend models for the active session.

Command	What it does
`aomi model list`	List models available to the current backend
`aomi model set <rig>`	Set the active model for the current session
`aomi model current`	Show the current model

aomi model list
aomi model set claude-sonnet-4
aomi model current

aomi model set persists the selected model in local session state after the backend confirms the change. aomi chat --model ... applies the model before sending and updates that persisted state too.

app

Command	What it does
`aomi app list`	List available apps
`aomi app current`	Show the current app

aomi app list
aomi app current

There is no aomi app use or aomi app set command. Switch apps with the --app <name> flag on a command, the AOMI_APP environment variable, or /app <name> inside the REPL.

chain

Command	What it does
`aomi chain list`	List supported chains
`aomi chain set <id>`	Persist the active chain ID
`aomi chain current`	Show the active chain ID

aomi chain list
aomi chain set 137
aomi chain current

For a single chain specific command, you can also pass --chain <id> on that command, or set AOMI_CHAIN_ID to share a chain across several commands. Run aomi chain list to see the chains your backend accepts.

wallet

Command	What it does
`aomi wallet set <privateKey>`	Persist a signing key and its derived wallet address
`aomi wallet current`	Show the configured wallet address

aomi wallet set 0xYourPrivateKey
aomi wallet current

config

Command	What it does
`aomi config set-backend <url>`	Persist the backend base URL
`aomi config current`	Show the configured backend URL

aomi config set-backend https://my-backend.example.com
aomi config current

secret

Ingest per session secrets so the backend uses opaque handles instead of raw values.

Command	What it does
`aomi secret list`	List configured secrets for the active session
`aomi secret add NAME=value [NAME=value ...]`	Add one or more secrets
`aomi secret clear`	Clear all secrets for the active session

aomi secret add ALCHEMY_API_KEY=sk_live_123
aomi secret add ALCHEMY_API_KEY=sk_live_123 TENDERLY_ACCESS_TOKEN=tok_456
aomi secret list
aomi secret clear

There is no aomi secret set command and no top level --secret flag. Add secrets only through aomi secret add NAME=value. Each value must use the NAME=value shape, or the command exits with an error.

To start a clean secret context, combine with --new-session:

aomi secret add ALCHEMY_API_KEY=sk_live_123 --new-session
aomi --prompt "simulate a swap on Base"

Transaction flow

The backend builds transactions. The CLI persists them locally, then signs and submits them when you choose.

Chat and queue a request

aomi chat "swap 1 ETH for USDC on Uniswap" --public-key 0xYourAddr --chain 1

When the agent needs a signature, the request is queued locally as tx-1. The CLI prints the destination, value, and chain.

Inspect pending transactions

aomi tx list

Pending (1):
  ⏳ tx-1  to: 0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD  value: 1000000000000000000  chain: 1  (2:14:07 PM)

Sign and submit

aomi tx sign tx-1 --private-key 0xYourPrivateKey

The CLI signs, submits, prints the hash, and notifies the backend.

The same flow handles EIP-712 typed data signatures. When the backend asks for a typed signature (for example a CoW Protocol order or a permit approval), it appears in aomi tx list with kind eip712_sign. The same aomi tx sign command handles both kinds.

Signing modes

By default aomi tx sign tries account abstraction first and falls back to direct EOA signing if AA is unavailable or fails. You can force a mode.

Flag	Behavior
(default)	AA first, automatic EOA fallback
`--aa`	Require AA. Error if no AA provider is configured
`--eoa`	Force direct EOA execution, skip AA

You can also constrain the AA provider and mode:

Flag	Accepted values
`--aa-provider <name>`	`alchemy` or `pimlico`
`--aa-mode <mode>`	`4337` or `7702`

--aa and --eoa are mutually exclusive. --aa-provider and --aa-mode cannot be combined with --eoa.

aomi tx sign tx-1 --private-key 0xYourPrivateKey --rpc-url https://eth.llamarpc.com
aomi tx sign tx-1 --aa --aa-provider alchemy --aa-mode 7702
aomi tx sign tx-1 --eoa

For Solana sign requests, pass a Solana keypair with --solana-private-key (a base58 secret key, or a JSON byte array), or set SOLANA_PRIVATE_KEY.

Flags and environment variables

These global flags work on the root command and on the subcommands. Flags take priority over environment variables.

Flag	Env variable	Description
`--backend-url <url>`	`AOMI_BACKEND_URL`	Backend base URL
`--api-key <key>`	`AOMI_API_KEY`	API key for non default apps
`--app <name>`	`AOMI_APP`	Active app
`--model <rig>`	`AOMI_MODEL`	Model to apply for the session
`--new-session`	n/a	Create a fresh active session for this command
`--chain <id>`	`AOMI_CHAIN_ID`	Active chain for chat and session context
`--public-key <address>`	`AOMI_PUBLIC_KEY`	Wallet address, so the agent knows your wallet
`--private-key <hex>`	`PRIVATE_KEY`	Hex signing key for `aomi tx sign`
`--solana-private-key <key>`	`SOLANA_PRIVATE_KEY`	Solana keypair for Solana sign requests
`--rpc-url <url>`	`CHAIN_RPC_URL`	RPC URL for transaction submission
`--aa-provider <name>`	`AOMI_AA_PROVIDER`	AA provider: `alchemy` or `pimlico`
`--aa-mode <mode>`	`AOMI_AA_MODE`	AA mode: `4337` or `7702`

Root command only flags:

Flag	Description
`-p`, `--prompt <prompt>`	Send a single prompt and exit
`--show-tool`	Show tool output in prompt or REPL mode
`--provider-key <provider:key>`	Save a BYOK provider key before running
`-v`, `--version`	Print the installed CLI version

--verbose (-v) is available on aomi chat to stream tool calls and responses live.

If you pass both --public-key and --private-key, the CLI checks that the public key matches the address derived from the private key and exits if they disagree. If you pass only --private-key, it derives the public key for you.

Wallet connection

Pass --public-key so the agent knows your address. This lets it build transactions and read your balances. The address is saved in state, so later commands in the same session do not need it again.

aomi chat "send 0 ETH to myself" \
  --public-key 0x5D907BEa404e6F821d467314a9cA07663CF64c9B

Fresh sessions

Use --new-session when a command should start a fresh backend and local session instead of reusing the active one.

aomi chat "show my balances" --new-session
aomi secret add ALCHEMY_API_KEY=... --new-session
aomi session new

How state works

The CLI is not a daemon. Each command starts, runs, and exits. Conversation history lives on the backend. Between runs, the CLI persists local state under AOMI_STATE_DIR, or ~/.aomi by default.

Field	Purpose
`sessionId`	Which conversation to continue
`clientId`	Stable client identity used for session secret handles
`model`	Last model successfully applied to the session
`publicKey`	Wallet address from `--public-key`
`chainId`	Active chain ID from `--chain`
`secretHandles`	Opaque handles returned for ingested secrets
`pendingTxs`	Unsigned transactions waiting for `aomi tx sign`
`signedTxs`	Completed transactions with hashes or signatures

Individual session files live under <state dir>/sessions/, with a pointer to the active session stored in the state root.

aomi chat "hello"           # creates a session, saves sessionId
aomi chat "swap 1 ETH"      # reuses the session, queues tx-1 on a wallet request
aomi tx sign tx-1           # signs tx-1, moves it to signedTxs, notifies the backend
aomi tx list                # shows all transactions
aomi session close          # clears the active local session pointer

Common tasks

A few flows you will reach for often. Each uses the commands documented above.

Chat with your App locally

Sanity check a preamble or a new tool before you deploy. The CLI talks to your App as deployed on the backend, so deploy a change first, then check it here.

aomi --app mycoindex                                        # open the REPL
aomi --prompt "what is the price of ETH?" --app mycoindex   # or one shot

Add --verbose to watch which tools the model calls and what they return. Run aomi session log to read the whole exchange back, tool results included.

Compare models

Run the same prompt across models without starting over.

aomi model list
aomi model set gpt-5
aomi chat "summarize my portfolio risk" --model claude-sonnet-4

Debug a tool call

When the model does not call the tool you expect, run the chat in verbose mode to see the tool calls, their arguments, and the raw results live.

aomi chat "what is the price of ETH?" --verbose

Simulate before you sign

When a chat asks the agent to act onchain, the transaction is queued locally. Simulate it before signing so no funds move until you are happy with the result. See Transaction flow for the full walkthrough.

Inspect or resume a session

Each conversation is a session, kept locally so you can pick it up later.

aomi session list
aomi session resume session-1
aomi session status

Next steps

Trade on Aomi

How the agent turns a prompt into a simulated, signed onchain trade.

The builder toolchain

The Rust toolchain for building and shipping Apps: aomi-build, aomi-run, aomi-git.

​Install

​Two ways to run it

Interactive REPL

Single message and scripting

​Interactive REPL

​Single prompt

​Commands

​chat

​tx

​session

​model

​app

​chain

​wallet

​config

​secret

​Transaction flow

​Signing modes

​Flags and environment variables

​Wallet connection

​Fresh sessions

​How state works

​Common tasks

​Chat with your App locally

​Compare models

​Debug a tool call

​Simulate before you sign

​Inspect or resume a session

​Next steps

Trade on Aomi

The builder toolchain

Install

Two ways to run it

Interactive REPL

Single prompt

Commands

chat

tx

session

model

app

chain

wallet

config

secret

Transaction flow

Signing modes

Flags and environment variables

Wallet connection

Fresh sessions

How state works

Common tasks

Chat with your App locally

Compare models

Debug a tool call

Simulate before you sign

Inspect or resume a session

Next steps