@namera-ai/cli 0.1.4 → 1.0.0

package/README.md

@@ -1,267 +1,137 @@
-# Namera CLI
-
-Namera CLI gives agents controlled access to smart accounts with session keys and scoped permissions, running fully local and agent-first across chains.
-
-<p>
-  <a href="https://www.npmjs.com/package/@namera-ai/cli"><img src="https://img.shields.io/npm/v/@namera-ai/cli" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/@namera-ai/cli"><img src="https://img.shields.io/npm/dm/@namera-ai/cli" alt="npm downloads"></a>
-  <a href="https://github.com/thenamespace/namera/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@namera-ai/cli" alt="license"></a>
-</p>
-
-## Contents
-
-- [Namera CLI](#namera-cli)
-  - [Contents](#contents)
-  - [Prerequisites](#prerequisites)
-  - [Installation](#installation)
-  - [Quick Start](#quick-start)
-  - [Why Namera CLI?](#why-namera-cli)
-  - [Command Groups](#command-groups)
-  - [Params Mode and Schema](#params-mode-and-schema)
-  - [Output Formats](#output-formats)
-  - [Session Key Policies](#session-key-policies)
-  - [MCP Server](#mcp-server)
-    - [MCP Params Mode](#mcp-params-mode)
-  - [Supported Chains](#supported-chains)
-  - [Environment Variables](#environment-variables)
-  - [Examples](#examples)
-  - [Documentation](#documentation)
-  - [Security](#security)
-  - [License](#license)
-
-## Prerequisites
-
-- **Node.js 18+** for running the CLI via npm/pnpm/bun
+# @namera-ai/cli
+
+Use Namera from your terminal, Codex, or Claude Code. Import encrypted session
+keys and execute within the permissions you approved. The CLI includes a local
+**stdio MCP server** that your agent client starts automatically.
 
 ## Installation
 
-Install globally with your package manager:
+Requires **Node.js 24.14+** and an available operating-system keyring.
 
-```bash
-npm i -g @namera-ai/cli
-#or
-pnpm i -g @namera-ai/cli
-#or
-bun i -g @namera-ai/cli
-#or
+```sh
+npm install -g @namera-ai/cli
+pnpm add -g @namera-ai/cli
 yarn global add @namera-ai/cli
-```
-Build from source:
-
-```bash
-gh repo clone thenamespace/namera
-cd namera
-pnpm install
-cd apps/cli
-pnpm run build
-pnpm run start -- --help
-# or link to global install
-pnpm link
-```
-
-## Quick Start
-
-Create a keystore, smart account, and session key (interactive prompts):
-
-```bash
-namera keystore create --alias my-owner
-```
-```bash
-namera smart-account create --alias my-smart --owner-alias my-owner
-```
-```bash
-namera session-key create --alias my-session-key --smart-account my-smart
-```
-
-Start the MCP server:
-
-```bash
-namera mcp start --smart-account my-smart --session-key my-session-key=my-password --transport http --port 8080
-```
-
-## Why Namera CLI?
-
-**For humans**: clear prompts, consistent flags, and readable output.
-
-**For agents**: every command has a JSON schema, supports deterministic `--params`, and returns structured output that is easy to parse.
-
-```bash
-# Schema discovery
-namera schema session-key.create
-```
-
-```bash
-# Deterministic params mode
-namera session-key create --params '{"alias":"my-session-key","smartAccountAlias":"my-smart","chains":["eth-mainnet"],"sessionKeyPassword":"session-password","ownerKeystorePassword":"owner-password","policyParams":[{"type":"sudo"}]}'
+bun add -g @namera-ai/cli
 ```
 
-## Command Groups
+Choose one command. `yarn global` requires Yarn Classic; with modern Yarn use
+`yarn dlx @namera-ai/cli --help` or install globally with npm/pnpm.
+Bun can install the package, but the executable runs on Node.js.
 
-- `keystore` (`k`): Create, import, list, inspect, decrypt, and remove keystores
-- `smart-account` (`sa`): Create, import, list, inspect, status, and remove smart accounts
-- `session-key` (`sk`): Create, list, inspect, status, and remove session keys
-- `schema`: Print JSON schema for command parameters
-- `mcp`: Start the local MCP server
-
-Explore help:
-
-```bash
+```sh
 namera --help
-namera keystore --help
-namera smart-account --help
-namera session-key --help
-namera mcp --help
-```
-
-## Params Mode and Schema
-
-Agents should use `--params` with the schema command to discover the exact input shape.
-
-```bash
-namera schema keystore.create
-namera schema smart-account.create
-namera schema session-key.create
-namera schema mcp.start
+namera --version
 ```
 
-Example params mode calls:
+## Sign in and inspect wallets
 
-```bash
-namera keystore create --params '{"alias":"my-owner","password":"my-password"}'
+```sh
+namera login
+namera wallet list
+namera session-key list
+namera wallet get <wallet-id>
+namera session-key get <session-key-id>
 ```
 
-```bash
-namera smart-account create --params '{"alias":"my-smart","ownerAlias":"my-owner","ownerPassword":"my-password","index":0}'
-```
-
-```bash
-namera session-key create --params '{"alias":"my-session-key","smartAccountAlias":"my-smart","chains":["eth-mainnet"],"sessionKeyPassword":"session-password","ownerKeystorePassword":"owner-password","policyParams":[{"type":"sudo"}]}'
-```
+Login opens browser consent to choose access. Credentials persist in the OS
+keyring, so you do not sign in for every command. The default API is
+`https://api.namera.ai`.
 
-## Output Formats
+For local development:
 
-All commands support global output flags:
-
-- `--output`, `-o`: `pretty` (default), `json`, or `ndjson`
-- `--quiet`, `-q`: Suppress output entirely
-
-```bash
-namera smart-account list --output json
-namera session-key list --output ndjson
+```sh
+namera login --profile dev --host http://localhost:8080
+namera wallet list --profile dev
 ```
 
-## Session Key Policies
-
-Session keys are scoped by one or more policies:
+## Import a session key
 
-- `sudo`: Full permission, no restrictions
-- `call`: Restrict targets, functions, and value limits
-- `timestamp`: Limit validity by time range
-- `gas`: Limit total gas spend and optionally require a paymaster
-- `rate-limit`: Limit number of requests per interval
-- `signature-caller`: Restrict who can validate signatures
+Create a key in the dashboard, approve its networks, and encrypt its export.
+Run the command shown in the dashboard:
 
-Example policy payload:
-
-```json
-{ "type": "timestamp", "validAfter": 1719916800, "validUntil": 1722604800 }
+```sh
+namera session-key import <encrypted-export>
 ```
 
-## MCP Server
+The export passphrase is entered privately. The CLI re-encrypts the key with an
+independent OS-keyring secret and stores an encrypted local file. It never falls
+back to plaintext storage. Keep your encrypted backup and passphrase safe.
+Importing does not install the key onchain or grant a client access to it.
 
-Start MCP over stdio (default):
+## Connect an agent
 
-```bash
-namera mcp start --smart-account my-smart --session-key my-session-key=my-password
-```
+Register once with your chosen client:
 
-Start MCP over HTTP:
+```sh
+# Codex
+codex mcp add namera -- namera mcp serve --profile codex
 
-```bash
-namera mcp start --smart-account my-smart --session-key my-session-key=my-password --transport http --port 8080
+# Claude Code
+claude mcp add --transport stdio --scope user namera -- namera mcp serve --profile claude
 ```
 
-HTTP endpoint: `http://localhost:8080/mcp`
-
-Tools exposed:
+Other MCP clients use command `namera` and arguments
+`["mcp", "serve", "--profile", "agent"]`.
 
-- `get_wallet_address`
-- `get_balance`
-- `read_contract`
-- `native_transfer`
-- `execute_transaction`
+Your client starts the process: no manual daemon or HTTP MCP endpoint is needed.
+First tool use opens browser authorization. Approve access to installed session
+keys and retry the tool after consent. If the browser cannot open:
 
-### MCP Params Mode
-
-```bash
-namera mcp start --params '{"smartAccountAlias":"my-smart","transport":"http","port":8080,"sessionKeys":{"my-session-key":"my-password"}}'
+```sh
+namera mcp login --profile codex
+namera mcp status --profile codex
 ```
 
-## Supported Chains
-
-See the supported chain keys and IDs on [Namera Documentation](https://namera.ai/docs/cli/supported-chains).
-
-## Environment Variables
+MCP authorization is separate from ordinary CLI login. Use the same profile and
+`--host` for serve/login/status/logout. Import signing keys on this machine
+before executing or signing. Credentials survive restarts. The CLI does not
+automatically export telemetry from your machine.
 
-You can pass chain-specific environment variables when starting MCP:
+## Simulate, execute, and sign
 
-```bash
-# Ethereum Mainnet
-export ETH_MAINNET_RPC_URL="https://mainnet.infura.io/v3/YOUR-PROJECT-ID"
-export ETH_MAINNET_BUNDLER_URL="https://rpc.zerodev.app/api/v3/<api-token>/chain/1"
-export ETH_MAINNET_PAYMASTER_URL="https://rpc.zerodev.app/api/v3/<api-token>/chain/1"
-
-# Polygon Mainnet
-export POLYGON_MAINNET_RPC_URL="https://polygon-rpc.com"
-export POLYGON_MAINNET_BUNDLER_URL="https://rpc.zerodev.app/api/v3/<api-token>/chain/137"
-export POLYGON_MAINNET_PAYMASTER_URL="https://rpc.zerodev.app/api/v3/<api-token>/chain/137"
-
-# ... and more
+```sh
+namera execution simulate
+namera execution execute
+namera execution status <submission-id>
+namera execution list
+namera sign
+namera verify-signature
 ```
 
-By default, MCP uses the public RPC and public Pimlico Bundler RPC: `https://public.pimlico.io/v2/{chain_id}/rpc`.
-
-## Examples
+Commands prompt for inputs. For automation, pass `--params '<json>'` using the
+public request shape. Execution/signing requires an imported key, active grant,
+and appropriate authority. Gas is sponsored by default. Self-funded operations
+also require `--max-gas-cost-wei <amount>`; MCP tools cannot raise that ceiling.
 
-Create a keystore and smart account:
+## Script-friendly output
 
-```bash
-# Create a keystore
-namera keystore create -a my-owner -p my-password
+```sh
+namera --output json wallet list
+namera --output ndjson session-key list
+namera --quiet auth status
 ```
 
-```bash
-# Create a smart account
-namera smart-account create -a my-smart -oa my-owner -op my-password -i 0
-```
-
-Create a session key (interactive policy selection):
-
-```bash
-namera session-key create -a my-session-key -sa my-smart
-```
+Human-readable summaries are the default. JSON includes complete response fields;
+NDJSON emits one document per top-level list item. `NO_COLOR` disables styling.
+MCP reserves stdout for the protocol and writes diagnostics to stderr.
 
-Check deployment status:
+For headless API-key use, supply `NAMERA_API_KEY` through the environment;
+`NAMERA_API_URL` overrides the default host. API keys take precedence over
+ordinary CLI profile credentials, but do not authorize MCP.
 
-```bash
-# Check smart account deployment status on Ethereum Mainnet
-namera smart-account status --alias my-smart --chain eth-mainnet
-```
+## Sign out
 
-```bash
-# Check session key installation status on Ethereum Mainnet
-namera session-key status --alias my-session-key --chain eth-mainnet
+```sh
+namera logout
+namera mcp logout --profile codex
 ```
 
-## Documentation
-
-- CLI Docs: [https://namera.ai/docs/cli](https://namera.ai/docs/cli)
-- CLI Docs Source: [apps/docs/content/docs/cli](https://github.com/thenamespace/namera/tree/main/apps/docs/content/docs/cli)
-
-## Security
-
-Please report security issues via GitHub: https://github.com/thenamespace/namera/security
-
-## License
+Logout revokes that authorization, not other profiles or signing keys. macOS
+Keychain integration is tested; Windows/Linux still need platform verification.
+Headless Linux needs an accessible Secret Service/keyring. There is no plaintext
+or in-memory fallback.
 
-Apache 2.0. See [LICENSE](https://github.com/thenamespace/namera/blob/main/LICENSE).
+See [local MCP](https://github.com/thenamespace/namera-core/blob/main/architecture/clients/local-mcp.md)
+and [key storage](https://github.com/thenamespace/namera-core/blob/main/architecture/clients/local-keystore.md).
+The four public packages share a release version starting with 1.0.0.