CLI Reference
The agentaos CLI manages agent accounts, signs transactions, and deploys contracts from your terminal. Every signing operation uses 2-of-3 threshold ECDSA. The full private key never exists.
Both agentaos and the short alias agenta are available after install. All examples below use agenta.
Install
Global Options
| Flag | Description |
|---|
-s, --signer <name> | Signer name (default: auto-detected from ~/.agenta/) |
-V, --version | Print version |
-h, --help | Show help |
Commands
| Command | Description |
|---|
agenta init | Create or import a signer |
agenta login | Authenticate with email + OTP |
agenta logout | Log out (clear session) |
agenta status | List all signers with live status |
agenta info [name] | Show full signer details (copyable) |
agenta balance | Check ETH balance |
agenta send <to> <amount> | Send ETH |
agenta sign-message <message> | Sign an arbitrary message |
agenta deploy <bytecode> | Deploy a smart contract |
agenta proxy | Start JSON-RPC signing proxy |
agenta network | Manage networks (list, set, get, info) |
agenta link [signer] | Send recovery key to AgentaOS via 6-word transfer code |
agenta receive [signer] | Import share from another device |
agenta admin | Manage guardrails and audit logs |
agenta init
Interactive setup wizard. Create a new signer or import an existing one.
Three options:
- Create a new signer — runs DKG, generates 3 shares, saves config locally
- Import existing signer — connect with an API key and signer secret
- Switch active signer — change which signer is used by default
DKG takes under 10 seconds. The server generates all 3 shares. Your signer share is saved locally. The server share goes to Vault. The user share is encrypted with your passkey.
agenta login
Authenticate with email and OTP.
agenta login
agenta login --server https://your-server.com
| Flag | Description |
|---|
--server <url> | Server URL (default: AGENTA_SERVER env or https://api.agentaos.ai) |
agenta status
Show all signers with live server status, balances, and policy counts.
● my-agent 0x1a2b…3c4d active 3 pol
staging 0x5e6f…7a8b paused 1 pol
Active: my-agent · 2 signers
agenta info
Show full details for a signer. Useful for copying addresses and API keys.
agenta balance
Check ETH balance on a specific network.
agenta balance -n base-sepolia
| Flag | Description |
|---|
-n, --network <network> | Network name (falls back to configured default if omitted) |
agenta send
Send ETH to an address. Signs via threshold ECDSA and broadcasts.
agenta send 0xRecipient 0.01 -n base-sepolia
| Argument / Flag | Description |
|---|
<to> | Destination address (0x…) |
<amount> | Amount in ETH (e.g. 0.01) |
-n, --network <network> | Network name |
--gas-limit <limit> | Override gas limit |
--data <hex> | Calldata as hex string |
The server evaluates all active guardrails before co-signing. If any guardrail blocks the transaction, you get a 403 with the list of violations.
agenta sign-message
Sign an arbitrary message using threshold ECDSA. Returns v, r, s, and the full signature.
agenta sign-message "Hello from Agenta"
agenta sign-message 0xdeadbeef
| Argument | Description |
|---|
<message> | Message to sign (string or hex with 0x prefix) |
agenta deploy
Deploy a smart contract. Pass bytecode as hex or a file path.
agenta deploy ./out/MyContract.sol/MyContract.bin -n base-sepolia
| Argument / Flag | Description |
|---|
<bytecode> | Contract bytecode (hex string or file path) |
-n, --network <network> | Network name |
--constructor-args <args> | ABI-encoded constructor arguments (hex) |
agenta proxy
Start a JSON-RPC signing proxy. Intercepts eth_sendTransaction and eth_signTransaction, signs via Agenta, forwards everything else to the upstream RPC.
| Flag | Description |
|---|
-p, --port <port> | Port to listen on (default: 8545) |
-r, --rpc-url <url> | Override upstream RPC URL |
agenta network
Manage networks — list available chains, set your default.
| Subcommand | Description |
|---|
agenta network list | List all available networks |
agenta network set <name> | Set the default network |
agenta network get | Show the current default network |
agenta network info <name> | Show details for a specific network |
agenta link
Send recovery key to AgentaOS via a 6-word transfer code.
agenta link
agenta link my-agent --server https://your-server.com
| Argument / Flag | Description |
|---|
[signer] | Signer name (optional, auto-detected if omitted) |
--server <url> | Server URL override |
agenta receive
Import a share from another device using a transfer code.
agenta receive
agenta receive my-agent --server https://your-server.com
| Argument / Flag | Description |
|---|
[signer] | Signer name (optional) |
--server <url> | Server URL override |
agenta admin
Manage guardrails and audit logs.
| Subcommand | Description |
|---|
agenta admin policies edit | Interactive policy editor |
agenta admin pause | Pause signer (blocks all signing) |
agenta admin resume | Resume a paused signer |
agenta admin audit | View signing history |
| Flag | Description |
|---|
--limit <n> | Max audit entries to show (for audit) |
--status <status> | Filter: completed, blocked, failed, pending (for audit) |
--export | Export audit log as CSV (for audit) |
Configuration
All config lives in ~/.agenta/.
| File | Purpose |
|---|
~/.agenta/signers/{name}.json | Signer config (server URL, API key, address, embedded secret) |
~/.agenta/.default | Name of the active signer |
interface SignerConfig {
version: 1;
serverUrl: string;
apiKey: string;
apiSecret?: string; // Base64-encoded key share (inline)
network?: string; // Default network name
signerName: string;
ethAddress: string;
signerId?: string;
createdAt?: string;
}
Signer secrets are stored as a base64 apiSecret field in the JSON config file. The CLI never sends your signer share to the server. All config files are saved with mode 0o600 (read/write owner only).
