MegaETH MOSS CLI

Command-line access to a MegaETH MOSS account. Connect your passkey account, create scoped delegated keys, inspect live permissions, and submit reads or writes from a terminal or automation workflow.

Warning: This is early software. Use scoped keys, review wallet prompts, and avoid approving more spend or call authority than a workflow needs.

Install

Shell Script

Note: The hosted install URL bootstraps the canonical installer published with each GitHub Release. The release installer downloads a versioned archive and verifies its .sha256 checksum before installing.

On Windows, run this command inside WSL or Git Bash.

curl -fsSL https://account.megaeth.com/install | sh

The installer downloads the latest release, verifies its checksum, installs the mega command, and installs the bundled agent skill for Codex, Claude, Hermes, and OpenClaw. Add the printed install directory to PATH if needed. Release installs smoke-check the new CLI before pruning stale release directories. Release installs also check for CLI updates before launching, with the check throttled to avoid a network request on every command.

Release tags use strict vX.Y.Z versions. The release packager verifies that the tag matches both the package version and the version reported by mega moss --version before producing publishable artifacts.

Install a specific release:

curl -fsSL https://account.megaeth.com/install | sh -- --version v0.1.0

Prefer to inspect the artifact manually first? See the GitHub Releases page.

Agent Skill Only

The release installer installs the bundled agent skill automatically. To install or refresh only the skill through the open skills installer:

npx skills add megaeth-labs/wallet-cli

Build From Source

git clone https://github.com/megaeth-labs/wallet-cli
cd wallet-cli
pnpm install
pnpm build
./scripts/install.sh

Requires Node.js 22 or newer and pnpm.

Source installs are development installs. They use the same install root and uninstall path as releases, but they do not auto-check for updates before launching. Run mega moss update if you want to replace a source install with the latest release build.

Update

mega moss update

Use mega moss update --check to check without installing. The explicit update command uses the same public release installer and also refreshes the bundled agent skill.

Quick Start

# Connect this machine to your MOSS account
mega moss login

# Check the connected account and active delegated key
mega moss whoami

# Create a scoped key for USDm transfers
mega moss create-key \
  --spend-limit 0xfafddbb3fc7688494971a79cc65dca3ef82079e7:25:week \
  --allow-call '0xfafddbb3fc7688494971a79cc65dca3ef82079e7:transfer(address,uint256)' \
  --label usdm-transfer

# Send through the active delegated key
mega moss transfer \
  --token 0xfafddbb3fc7688494971a79cc65dca3ef82079e7 \
  --to 0xabcdefabcdefabcdefabcdefabcdefabcdefabcd \
  --amount 1

Login opens account.megaeth.com in your browser and stores a local account profile. It does not create a write-capable key. Use create-key to approve a delegated key with explicit call and spend scope.

Account And Key Model

MegaETH MOSS CLI is not a root wallet or passkey manager. Your passkey stays in MegaETH Wallet. The CLI stores local delegated session-key material only after you approve it in the browser.

Delegated keys are bounded by:

• expiry
• token/native spend limits
• allowed contract calls
• account and relay enforcement

Use narrow keys. A key that can transfer USDm should not also be able to call an unrelated protocol unless the workflow needs that permission.

Output Formats

Human output is the default:

mega moss list
mega moss permissions 0xKEY_OR_ACCESS_ADDRESS

Machine-readable output:

mega moss whoami --json
mega moss list --json
mega moss permissions 0xKEY_OR_ACCESS_ADDRESS --json

Compact tab-delimited output:

mega moss whoami --terse

Use --json or --terse for noninteractive inspection and scripting. Human mode may include terminal color or login helpers. Human device-code authorization prints a terminal QR on stderr by default, including in a chat shell or other non-TTY output. Every QR presentation uses the same channel-neutral instruction:

Scan this QR code or open this link in a browser where your wallet is available.

Eligible terminals use ANSI contrast; other human-output contexts use plain Unicode. --json and --terse omit the terminal QR so their output remains plain and stable. --terse means compact tab-delimited final output; it is not a headless, chat, or QR-presentation mode. Do not use either machine mode when a user-visible terminal QR is required.

--qr-file <absolute-path.png> is an advanced host-integration option. It writes a temporary mode-0600 PNG but does not display or attach it. Use it only when the caller explicitly requested a PNG and has a verified image-attachment API; a local path is not user-visible. The CLI removes the file when authorization finishes normally. A forced process kill may leave the file behind; it contains only the soon-expired verification URL and should be deleted. --qr-file requires --auth-flow device. An explicit host integration may combine it with --json or --terse, but both modes still suppress the terminal QR.

Commands

Login

mega moss login

Connects the local CLI profile to your MOSS account. Browser authorization uses same-machine loopback. The CLI normally opens the browser and prints the authorization URL as a fallback while it waits. The legacy --no-browser flag only suppresses automatic opening and prints that URL immediately; use it when that explicit behavior is desired.

Use device auth when the user explicitly requests it or approval must happen in a browser that cannot complete the CLI's loopback callback, typically on a different machine or device:

mega moss login --auth-flow device

Device auth says, “Scan this QR code or open this link in a browser where your wallet is available.” In human output, it follows that instruction with a QR code for the complete verification URL, even when stderr is a chat shell or another non-TTY stream. The URL, verification code, direct link, and expiry are always printed as a fallback before the CLI waits for approval in MegaETH Wallet. The same device flow is available for create-key and revoke.

For a chat handoff, agents must use human mode with none of --json, --terse, or --qr-file. Capture the complete static prompt before presenting any of it. Strip ANSI escape sequences and carriage returns, preserve every remaining space and line break, exclude polling or status lines, and present the neutral instruction plus QR in one fenced text block. Do not forward partial QR chunks or interleave “Waiting for approval” output. The chat UI may still render the completed fenced block progressively; the agent cannot guarantee atomic client-side painting. After the block, repeat the CLI-supplied direct link as a clickable link and include the user code and expiry.

Agents must not choose --qr-file autonomously. It is reserved for an explicit host integration with a previously verified image-attachment API; shell or file access is insufficient. If preformatted text cannot be preserved, use a link-only fallback and do not claim that a QR was shown. --json or --terse may intentionally suppress the terminal QR for that fallback, but they must not be used when the task requires a visible QR.

The handoff must reach the user while authorization is still pending. Run the command as a persistent live process that yields initial output promptly. In text chat, never invoke the device-auth CLI directly as a foreground tool call, even when that tool claims to stream output. Use its background/session mode, or one background supervisor writing to a private temporary log and an atomic completion/status file. Inspect output immediately and use Waiting for approval... as the complete-prompt marker; poll on that marker and the completion file instead of using a blind fixed sleep. Return control while the process is still alive, send the QR, clickable direct link, CLI-supplied user code, and expiry in assistant-visible chat, and only then wait for the completion file in another tool call. Do not use kill -0 alone for completion because a zombie process still satisfies it. Raw or collapsed tool output, a background log, and a local file path must not be assumed visible to the user. A handoff first shown after approval or command completion is not successful. Never expose the backend device code or PKCE verifier, and never send the verification link to an external QR service. The advanced --qr-file option is available on device-auth login, create-key, and revoke; its output mode and cleanup rules are described above.

When the wallet cannot approve a request, the CLI may include a short reason in the terminal error, such as an unavailable fee token or a browser-wallet account mismatch. Correct that condition before starting a new authorization; do not repeat the same request unchanged. A plain cancellation remains a generic cancellation without inferred recovery advice.

If a profile already exists, login exits before opening the browser. Use create-key to add a delegated key, or logout to forget the local profile. logout is local-only and does not revoke keys on-chain.

Keys

mega moss whoami
mega moss list
mega moss list --show-inactive
mega moss permissions 0xKEY_OR_ACCESS_ADDRESS
mega moss switch 0xKEY_OR_ACCESS_ADDRESS
mega moss label 0xKEY_OR_ACCESS_ADDRESS "agent"

permissions shows the approved scope and, when RPC is available, live on-chain spend remaining. In JSON output, authorizedKey.permissions.spend is the stored request and spendInfos[].remaining is the live remaining capacity.

Create a key:

mega moss create-key \
  --spend-limit 0xfafddbb3fc7688494971a79cc65dca3ef82079e7:25:week \
  --allow-call '0xfafddbb3fc7688494971a79cc65dca3ef82079e7:transfer(address,uint256)' \
  --label agent

Each --spend-limit is <token_address>:<amount>:<period>. Use 0x0000000000000000000000000000000000000000 for native ETH. Amount is a human token amount. Period is minute, hour, day, week, month, or year.

Each --allow-call is <contract_address>:<function_signature>. Write keys must have explicit call scope. Empty or omitted call permissions cannot execute relay-backed writes. For native ETH transfers, scope the recipient target with the no-calldata selector 0xe0e0e0e0.

For advanced permission files, see references/permissions.md.

Revoke

mega moss revoke 0xKEY_OR_ACCESS_ADDRESS
mega moss revoke 0xKEY_OR_ACCESS_ADDRESS --fee-token USDm

Revokes a delegated key on-chain after browser confirmation. After success, the CLI removes local private key material for that key and keeps an inactive audit record. On revoke only, --fee-token selects the relay payment token for the revoke transaction itself.

Reads

mega moss call \
  --to 0x1234567890abcdef1234567890abcdef12345678 \
  --data 0x

ABI mode:

mega moss call \
  --to 0x1234567890abcdef1234567890abcdef12345678 \
  --abi ./erc20.json \
  --function balanceOf \
  --args '["0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"]'

call is read-only and does not require a delegated write key.

Writes

mega moss execute \
  --to 0x1234567890abcdef1234567890abcdef12345678 \
  --data 0x \
  --value 0

Multiple calls:

mega moss execute --calls ./calls.json

Selected key:

mega moss execute --key 0xKEY_OR_ACCESS_ADDRESS --calls ./calls.json

Spend permission is not call permission. Select or create a key whose spend limits and call scopes cover the operation.

Transfers

Native ETH:

mega moss transfer \
  --to 0xabcdefabcdefabcdefabcdefabcdefabcdefabcd \
  --amount 0.1

ERC20:

mega moss transfer \
  --token 0x1234567890abcdef1234567890abcdef12345678 \
  --to 0xabcdefabcdefabcdefabcdefabcdefabcdefabcd \
  --amount 100

The CLI reads ERC20 decimals from RPC by default.

Funding And Debugging

mega moss fund
mega moss debug
mega moss debug --skip-chain --json

debug inspects local profile health without printing private key material.

Fees

Workflow token/native movement uses permissions.spend. Relay fee preference uses the delegated key's feeToken metadata.

Use --fee-token <symbol> and optional --fee-limit <amount> on create-key to request delegated-key relay-fee metadata. --fee-limit is a human amount in that token. If omitted, the CLI uses an approximate $1 buffer in the selected fee token. The CLI sends it as feeToken and adds or merges matching fee spend capacity into permissions.spend. Add explicit --spend-limit rows for workflow token/native movement. The wallet UI user may still select the Gas Token for the approval transaction itself, and later writes default to the authorizedKey.feeToken returned by approval. Supported shorthand fee-token symbols are ETH, USDM, USDT0, and MEGA on mainnet, and ETH, USDM, and TST on testnet.

Logout And Uninstall

mega moss logout

Deletes the local profile and delegated private key material for this CLI install. It does not revoke on-chain keys.

Remove installed CLI files:

~/.mega/wallet-cli/current/scripts/uninstall.sh

Remove installed CLI files and local profiles:

~/.mega/wallet-cli/current/scripts/uninstall.sh --config

Help

mega moss --help
mega moss <command> --help