# MOSS CLI

The MOSS CLI package grants the ability to access your MOSS wallet and perform actions directly from a terminal.
This is especially useful for integrating with AI agents.

The CLI exposes the ability to log in to your account at `account.megaeth.com`, create a session key with specific
permissions and allowances, and then use that key to perform actions.

[Learn more about permissions](https://moss.megaeth.com/developers/concepts/permissions)

> [!NOTE]
> The CLI cannot perform admin tasks or execute outside of the permissions you grant

## Install

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

This installs the `mega` command and the MOSS agent skill for Codex, Claude, Hermes and OpenClaw.
If the installer prints an install directory, add it to your `PATH`. On Windows, run it in WSL or
Git Bash.

> [!NOTE]
> Update later with mega moss update (use --check to check without installing).

## Quick Start

Connect the CLI to your account. This opens `account.megaeth.com` to approve.

```bash
mega moss login
```

Create a key that can only send up to 25 USDm a week.

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

Execute a transfer.

```bash
mega moss transfer \
--token 0xfafddbb3fc7688494971a79cc65dca3ef82079e7 \
--to 0xabcdefabcdefabcdefabcdefabcdefabcdefabcd \
--amount 1
```

## Keys and Permissions

Each key the CLI uses is a [permission grant](https://moss.megaeth.com/developers/concepts/permissions) on your account,
limited by:

- An expiry
- How much of each token it can spend, and how often
- Which contract functions it can call

Each `--spend-limit` is `<token address>:<amount>:<period>`. Use the zero address for ETH. The
amount is in whole tokens, and the period is `minute`, `hour`, `day`, `week`, `month` or `year`.

Each `--allow-call` is `<contract address>:<function signature>`. A key needs at least one to
write. A spend limit on its own doesn't let a key call anything. To send ETH to an address, allow
the selector `0xe0e0e0e0` on that address.

```bash
mega moss whoami                    # The account and the key in use
mega moss list                      # Every key on this machine
mega moss permissions 0xKEY         # What a key can do, and how much it has left to spend
mega moss switch 0xKEY              # Use a different key for writes
mega moss revoke 0xKEY              # Remove a key from your account
```

`revoke` removes the key on chain, after you approve it in the wallet. `logout` only forgets the
keys on this machine; they still work on chain until you revoke them.

## Reading and Writing

Read from a contract. This needs no key:

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

Write with the key in use, or choose one with `--key`:

```bash
mega moss execute --to 0x1234...5678 --data 0x...
mega moss execute --calls ./calls.json
```

Send ETH, or a token by its address:

```bash
mega moss transfer --to 0xabcd...abcd --amount 0.1
mega moss transfer --token 0x1234...5678 --to 0xabcd...abcd --amount 100
```

## Gas

Choose the token a key pays gas in when you create it, with `--fee-token` (`ETH`, `USDM`, `USDT0`
or `MEGA` on mainnet). Optionally cap it with `--fee-limit`. Without a limit, the CLI sets aside
about $1 of that token. To add funds to your account, run `mega moss fund`, which opens the
deposit flow.

## Networks

Commands use mainnet unless you pass `--network testnet`.

## Scripting and Agents

Add `--json` for JSON output, or `--terse` for compact tab-separated lines.

On a machine that can't open a browser, add `--auth-flow device` to `login`, `create-key` or
`revoke`. The CLI then shows a QR code and a link to approve from a browser where your wallet is
available.

For agents, the installed skill covers how to show that QR code in a chat and keep the command
running until it's approved.

## Updating and Removing

```bash
mega moss update            # Install the latest release and skill
mega moss update --check    # Check for an update without installing it
mega moss debug             # Check the local setup (never prints keys)
mega moss logout            # Forget the account and keys on this machine
~/.mega/wallet-cli/current/scripts/uninstall.sh --config   # Remove the CLI and its profiles
```
