Skip to content

SETUP.md

Latest commit

 

History

History
193 lines (140 loc) · 7.99 KB

SETUP.md

File metadata and controls

193 lines (140 loc) · 7.99 KB
Raw

EmblemAI Setup Guide

Prerequisites

  • Node.js >= 20.18.0
  • Terminal with 256-color support (iTerm2, Kitty, Windows Terminal, or any xterm-compatible terminal)
  • Optional: glow for rich markdown rendering (brew install glow on macOS)

Installation

From npm

npm install -g @emblemvault/agentwallet

From source

git clone https://github.com/EmblemCompany/EmblemAi-cli.git
cd EmblemAi-AgentWallet-Plugins/cli
npm install
npm link   # makes `emblemai` available globally

Authentication

EmblemAI v3 supports two authentication modes: browser auth for interactive use and password auth for agent/scripted use.

Browser Auth (Interactive Mode)

When you run emblemai without -p, the CLI:

  1. Resolves the active profile from --profile, ~/.emblemai/active-profile, or default
  2. Checks ~/.emblemai/profiles/<profile>/session.json for a saved session
  3. If a valid (non-expired) session exists, restores it instantly -- no login needed
  4. If no session, starts a local server on 127.0.0.1:18247 and opens your browser
  5. You authenticate via the EmblemVault auth modal in the browser
  6. The session JWT is captured, saved to disk, and the CLI proceeds
  7. If the browser can't open, the URL is printed for manual copy-paste
  8. If authentication times out (5 minutes), falls back to a password prompt

Password Auth (Agent Mode and -p flag)

Login and signup are the same action -- the first use of a password creates a vault, and subsequent uses of the same password return the same vault.

Password auth is a core feature for agent workflows because it gives repeatable wallet access without requiring browser auth each time.

Password requirements

  • Minimum 16 characters
  • No recovery if lost (treat it like a private key)
  • Different passwords produce completely different wallets and identities
  • If the CLI auto-generates a password for agent mode, back it up after first wallet creation

Password resolution (priority order)

Method How to use Priority
CLI argument emblemai -p "your-password-16-chars-min" 1 (highest, stored encrypted)
Environment variable export EMBLEM_PASSWORD="your-password" 2 (not stored)
Encrypted credential dotenvx-encrypted ~/.emblemai/profiles/<profile>/.env 3
Auto-generate (agent mode) Automatic on first run 4
Interactive prompt Fallback when browser auth fails 5 (lowest)

In agent mode, if no password is found from sources 1-3, a secure random password is auto-generated and stored encrypted. This means agent mode works out of the box with no manual password setup.

What happens on authentication

  1. Browser auth: session JWT is received from browser and hydrated into the SDK Password auth: password is sent to EmblemAuthSDK.authenticatePassword()
  2. A deterministic vault is derived -- same credentials always yield the same vault
  3. The session provides wallet addresses across multiple chains: Solana, Ethereum, Base, BSC, Polygon, Hedera, Bitcoin
  4. HustleIncognitoClient is initialized with the session
  5. Plugins are loaded and registered with the client

Running Modes

Interactive Mode (Default)

Readline-based interactive mode with streaming, glow rendering, and slash commands.

emblemai              # Browser auth (recommended)
emblemai --profile treasury
emblemai -p "your-password"  # Password auth (skips browser)

Agent Mode

Single-shot queries for scripts and AI agent integrations. Sends one message, prints the response, and exits. Always uses password auth.

If more than one profile exists in $HOME/.emblemai, every agent-mode invocation must include --profile <name>. Agent mode never guesses which wallet identity to use.

emblemai --agent -p "your-password" -m "What are my wallet addresses?"
emblemai -a -p "your-password" -m "Show all my balances"
emblemai --profile treasury --agent -m "Show my balances"

Reset Conversation

emblemai --reset

Auth Backup and Restore

Backup

From the /auth menu (option 8), select Backup Agent Auth to export your credentials to a JSON file. This file contains your EmblemVault password -- keep it secure.

If you are using password auth, especially auto-generated password auth in agent mode, this backup should be treated as part of initial setup rather than an optional cleanup step.

Restore

emblemai --restore-auth ~/emblemai-auth-backup.json

This restores the credential files into the resolved active profile. If you pass --profile <name>, restore writes into that profile and creates it first when needed.

Command-Line Flags

Flag Alias Description
--password <pw> -p Authentication password (16+ chars) -- skips browser auth
--profile <name> Select a named wallet profile for this invocation. Required in agent mode when more than one profile exists.
--message <msg> -m Message for agent mode
--agent -a Run in agent mode (single-shot, password auth only)
--restore-auth <path> Restore credentials from backup file and exit
--reset Clear conversation history and exit
--debug Start with debug mode enabled
--stream Start with streaming enabled (default: on)
--log Enable stream logging
--log-file <path> Override log file path (default: ~/.emblemai-stream.log)
--hustle-url <url> Override Hustle API URL
--auth-url <url> Override auth service URL
--api-url <url> Override API service URL

Environment Variables

Variable Description
EMBLEM_PASSWORD Authentication password
HUSTLE_API_URL Override Hustle API endpoint
EMBLEM_AUTH_URL Override auth service endpoint
EMBLEM_API_URL Override API service endpoint
ELIZA_URL ElizaOS agent URL for inverse discovery (default: http://localhost:3000)
ELIZA_API_URL Override ElizaOS API URL

CLI arguments override environment variables when both are provided.

First Run

  1. Install: npm install -g @emblemvault/agentwallet
  2. Run: emblemai
  3. Authenticate in the browser (or enter a password if prompted)
  4. Check /plugins to see which plugins loaded
  5. Type /help to see all commands
  6. Try: "What are my wallet addresses?" to verify authentication

File Locations

File Purpose
~/.emblemai/active-profile Persisted active profile name
~/.emblemai/profiles/<profile>/.env dotenvx-encrypted credentials (EMBLEM_PASSWORD)
~/.emblemai/profiles/<profile>/.env.keys dotenvx private decryption key (chmod 600)
~/.emblemai/profiles/<profile>/secrets.json auth-sdk encrypted plugin secrets
~/.emblemai/profiles/<profile>/session.json Saved browser auth session (auto-managed)
~/.emblemai/profiles/<profile>/history/{vaultId}.json Conversation history (per vault)
~/.emblemai/profiles/<profile>/x402-favorites.json Saved x402 favorite services
~/.emblemai-stream.log Stream log (when enabled)
~/.emblemai/profiles/<profile>/plugins.json Custom plugin definitions

Legacy credentials (~/.emblem-vault) are automatically migrated to the new dotenvx-encrypted format on first run. The old file is backed up to ~/.emblem-vault.bak.

Supported Chains

Solana, Ethereum, Base, BSC, Polygon, Hedera, Bitcoin

Troubleshooting

Issue Solution
"Password must be at least 16 characters" Use a longer password
"Authentication failed" Check network connectivity to auth service
Browser doesn't open for auth Copy the printed URL and open it manually
Session expired Run emblemai again -- it will open the browser for a fresh login
glow not rendering Install glow: brew install glow (optional, falls back to plain text)
Plugin not loading Check that the npm package is installed
MASQ not responding on :3001 Check ElizaOS plugin loaded via /plugins