update for v1.0.0

README.md

@@ -1,6 +1,6 @@
 # MetaMask Agent CLI Skills
 
-SKILLs for the MetaMask Agent CLI. These skills enable AI agents to authenticate, manage wallets, swap tokens, bridge across chains, trade perpetual futures, and more using the MetaMask Agent CLI.
+SKILLs for the MetaMask Agent CLI (`@metamask/agentic-cli` v1.0.0). These skills enable AI agents to authenticate, manage wallets, swap tokens, bridge across chains, trade perpetual futures, and more using the MetaMask Agent CLI.
 
 ## Skills
 

skills/metamask-agent-wallet/SKILL.md

@@ -4,7 +4,8 @@ description: Use when the user asks anything about blockchain wallets, transacti
 license: MIT
 metadata:
   author: metamask
-  version: "2.1.0"
+  version: "2.2.0"
+  cliVersion: "1.0.0"
 ---
 
 # MetaMask Agentic CLI Skill
@@ -28,6 +29,8 @@ Match the user's intent to a command and reference file, then read the reference
 | Sign in via email OTP | `mm login email` | [auth.md](references/auth.md) |
 | Sign out | `mm logout` | [auth.md](references/auth.md) |
 | Reset CLI session | `mm reset` | [auth.md](references/auth.md) |
+| Show CLI configuration | `mm config get` | [auth.md](references/auth.md) |
+| Set CLI configuration | `mm config set` | [auth.md](references/auth.md) |
 | Set BYOK mnemonic encryption password | `mm wallet password set` | [auth.md](references/auth.md) |
 | Change BYOK mnemonic encryption password | `mm wallet password change` | [auth.md](references/auth.md) |
 | Remove BYOK mnemonic encryption password | `mm wallet password remove` | [auth.md](references/auth.md) |
@@ -127,7 +130,29 @@ Always use `--toon` for command output unless the user explicitly requests a dif
 
 ## Preflight
 
-Always run preflight before any CLI operation.
+Run these checks before the first CLI operation in a session, in order.
+
+### 1. Version compatibility
+
+This skill is written for `@metamask/agentic-cli` **v1.0.0** (see `cliVersion` in the frontmatter). Check the installed version:
+
+```bash
+mm --version
+```
+
+The installed version is the value after `@metamask/agentic-cli/` (e.g. `@metamask/agentic-cli/1.0.0 darwin-arm64 node-v24.14.1`). Compare its `major.minor` against the pinned `cliVersion`. Optionally check the latest published version (best-effort; skip silently on network failure):
+
+```bash
+npm view @metamask/agentic-cli version
+```
+
+If the installed `major.minor` differs from the pinned `cliVersion`, or the installed version is behind the latest release, warn the user once and continue:
+
+> Version mismatch: installed CLI `<installed>`, this skill is pinned to `1.0.0`, latest release is `<latest>`. Command syntax in this skill may be inaccurate until they are aligned. Update the CLI with `npm install -g @metamask/agentic-cli@latest`, then re-install the skills with `npx skills add metaMask/agent-skills`.
+
+Run this check once per session. Do not block operations on it.
+
+### 2. Authentication
 
 ```bash
 mm auth status

skills/metamask-agent-wallet/references/auth.md

@@ -34,6 +34,10 @@ export MM_PASSWORD="mypassword"
 mm init --wallet byok
 ```
 
+### Note
+
+- In server-wallet mode, if the account already has a remote EVM wallet, `mm init` syncs it and loads the existing trading mode and policies instead of prompting for a new trading mode or creating a wallet.
+
 ## `init show` Command
 
 Display the current initialization settings (wallet mode, trading mode, policies).
@@ -130,9 +134,78 @@ This command does not support flags.
 mm logout
 ```
 
+## `config get` Command
+
+Show persisted CLI configuration. Does not require authentication.
+
+### Syntax
+
+```bash
+mm config get [env|verbose|format]
+```
+
+### Supported Keys
+
+| Key | Description |
+| --- | --- |
+| `env` | Target API environment: `prod`, `dev`, or `uat` (defaults to `prod` when unset) |
+| `verbose` | Whether verbose logging is persisted (`true` or `false`) |
+| `format` | Default output format: `json`, `text`, `yaml`, `toml`, or `toon` |
+
+Omit the key to return all values.
+
+### Example
+
+```bash
+mm config get
+mm config get env
+```
+
+## `config set` Command
+
+Persist a CLI configuration value in `~/.metamask/config.json`. Does not require authentication.
+
+### Syntax
+
+```bash
+mm config set <env|verbose|format> <value>
+```
+
+### Supported Keys
+
+| Key | Values |
+| --- | --- |
+| `env` | `prod`, `dev`, or `uat` |
+| `verbose` | `true` or `false` |
+| `format` | `json`, `text`, `yaml`, `toml`, or `toon` |
+
+### Overrides
+
+Persisted values can be overridden per invocation without changing `~/.metamask/config.json`:
+
+| Key | Override |
+| --- | --- |
+| `env` | `MM_ENV` environment variable |
+| `verbose` | `--verbose` / `-v` flag |
+| `format` | `--format`, `--json`, `--toon`, etc. |
+
+### Example
+
+```bash
+mm config set env prod
+mm config set env dev
+mm config set env uat
+mm config set format toon
+```
+
+### Note
+
+- Switch environments at any time with `mm config set env <prod|dev|uat>`.
+- Non-prod sessions are stored in env-scoped files under `~/.metamask/` (e.g. `session.dev.json`, `session.uat.json`); prod uses `session.json`.
+
 ## `reset` Command
 
-Clear the local CLI session entirely.
+Clear the local CLI session entirely, including auth credentials, wallet state, mnemonic, swap quotes, and persisted config.
 
 ### Syntax
 

skills/metamask-agent-wallet/references/errors.md

@@ -78,7 +78,9 @@ This reference lists error codes the CLI actually emits. SDK-only or remapped co
 | `MISSING_ID` | Missing ID parameter |
 | `MISSING_QUOTE_ID` | Missing quote ID |
 | `MISSING_SWAP_PARAMS` | Missing swap parameters |
-| `COMING_SOON` | Feature not yet available (e.g. `mm login qr`) |
+| `COMING_SOON` | Feature not yet available (e.g. `mm login qr` on production) |
+| `INVALID_CONFIG_KEY` | Unknown config key passed to `mm config get` or `mm config set` |
+| `INVALID_CONFIG_VALUE` | Invalid value for a config key (e.g. env not in `prod|dev|uat`) |
 
 ## Swap & Bridge Errors
 

skills/metamask-agent-wallet/workflows/login.md

@@ -6,9 +6,10 @@ Reference command syntax in `references/auth.md`.
 
 ## Flow
 
-1. Ask the user which login method they want: MetaMask Mobile QR, Google, or Email.
-2. Execute login.
-3. Verify with token.
+1. Confirm the target environment with `mm config get env` (set with `mm config set env` before login if not `prod`).
+2. Ask the user which login method they want: MetaMask Mobile QR, Google, or Email.
+3. Execute login.
+4. Verify with token.
 
 ## Login
 

skills/metamask-agent-wallet/workflows/onboarding.md

@@ -7,18 +7,34 @@ Reference command syntax in `references/auth.md` and `references/wallet.md`.
 ## Flow
 
 1. Check CLI installation.
-2. Login.
-3. Initialize wallet mode.
-4. Verify auth status.
-5. Show wallet address.
+2. Configure environment (if not using production).
+3. Login.
+4. Initialize wallet mode.
+5. Verify auth status.
+6. Show wallet address.
 
 ## Check CLI Installation
 
 ```bash
 mm --version
 ```
 
-If this fails, the CLI is not installed. Guide the user to install it before proceeding.
+If this fails, the CLI is not installed. Guide the user to install it with `npm install -g @metamask/agentic-cli@latest` before proceeding.
+
+Then run the version compatibility check from the skill `Preflight` section: compare the installed `major.minor` against the pinned `cliVersion` and the latest published release, and warn the user if they are out of sync.
+
+## Configure Environment
+
+Production (`prod`) is the default. Set the target environment **before** login if the user needs dev or uat:
+
+```bash
+mm config get env
+mm config set env dev
+```
+
+For a one-off override without persisting, use `MM_ENV=dev mm login` (or `uat`).
+
+To switch environments, run `mm config set env <prod|dev|uat>`.
 
 ## Login Flow
 
@@ -49,7 +65,11 @@ First check if the project is already initialized:
 mm init show
 ```
 
-If already initialized, skip this step. Otherwise, ask the user which wallet mode they want:
+If already initialized, skip this step.
+
+For server-wallet mode, if the account already has a remote wallet, `mm init` syncs it and reuses the existing trading mode — no trading-mode prompt.
+
+Otherwise, ask the user which wallet mode they want:
 - `server-wallet` (recommended) — keys are hosted by MetaMask infrastructure. No need to manage private keys or mnemonics.
 - `byok` — bring your own mnemonic. The user manages their own keys locally.
 

skills/metamask-agent-wallet/workflows/troubleshooting.md

@@ -8,6 +8,7 @@ Run or suggest these in order:
 
 ```bash
 mm --version
+mm config get env
 mm auth status
 mm <failing-command> --help
 ```
@@ -20,7 +21,7 @@ If `auth status` reports anything other than authenticated, fix authentication b
 | --- | --- | --- |
 | `mm: command not found` | Binary not installed or not on `PATH` | Check install and PATH |
 | Async command returns a polling id and appears stuck | Request was dispatched without `--wait` | Use `mm wallet requests list` or `mm wallet requests watch --polling-id <id>` |
-| Auth errors after previously working | Expired token or wrong environment | Check `mm auth status` and environment/session file |
+| Auth errors after previously working | Expired token or wrong environment | Check `mm config get env`, `mm auth status`, and the env-scoped session file under `~/.metamask/` |
 | `CHAIN_ID_MISMATCH` on typed data | Payload `domain.chainId` differs from `--chain-id` | Align the two chain IDs |
 | `MNEMONIC_LOCKED` or `WRONG_PASSWORD` | BYOK mnemonic is encrypted and password was wrong or missing | Set the correct `MM_PASSWORD` environment variable and re-run |
 | `ALREADY_ENCRYPTED` on `wallet password set` | Mnemonic already has a password | Use `mm wallet password change` instead |

skills/metamask-agent-workflows/SKILL.md

@@ -4,7 +4,8 @@ description: Use when the user needs to perform multi-step operations with the M
 license: MIT
 metadata:
   author: metamask
-  version: "2.0.0"
+  version: "2.1.0"
+  cliVersion: "1.0.0"
 ---
 
 # MetaMask Agent Workflows
@@ -30,7 +31,29 @@ Always use `--toon` for command output unless the user explicitly requests a dif
 
 ## Preflight
 
-Always run preflight before any CLI operation.
+Run these checks before the first CLI operation in a session, in order.
+
+### 1. Version compatibility
+
+This skill is written for `@metamask/agentic-cli` **v1.0.0** (see `cliVersion` in the frontmatter). Check the installed version:
+
+```bash
+mm --version
+```
+
+The installed version is the value after `@metamask/agentic-cli/` (e.g. `@metamask/agentic-cli/1.0.0 darwin-arm64 node-v24.14.1`). Compare its `major.minor` against the pinned `cliVersion`. Optionally check the latest published version (best-effort; skip silently on network failure):
+
+```bash
+npm view @metamask/agentic-cli version
+```
+
+If the installed `major.minor` differs from the pinned `cliVersion`, or the installed version is behind the latest release, warn the user once and continue:
+
+> Version mismatch: installed CLI `<installed>`, this skill is pinned to `1.0.0`, latest release is `<latest>`. Command syntax in this skill may be inaccurate until they are aligned. Update the CLI with `npm install -g @metamask/agentic-cli@latest`, then re-install the skills with `npx skills add metaMask/agent-skills`.
+
+Run this check once per session. Do not block operations on it.
+
+### 2. Authentication
 
 ```bash
 mm auth status

skills/metamask-agent-workflows/workflows/login.md

@@ -6,9 +6,10 @@ Reference command syntax in `references/auth.md`.
 
 ## Flow
 
-1. Ask the user which login method they want: MetaMask Mobile QR, Google, or Email.
-2. Execute login.
-3. Verify with token.
+1. Confirm the target environment with `mm config get env` (set with `mm config set env` before login if not `prod`).
+2. Ask the user which login method they want: MetaMask Mobile QR, Google, or Email.
+3. Execute login.
+4. Verify with token.
 
 ## Login
 

skills/metamask-agent-workflows/workflows/onboarding.md

@@ -7,18 +7,34 @@ Reference command syntax in `references/auth.md` and `references/wallet.md`.
 ## Flow
 
 1. Check CLI installation.
-2. Login.
-3. Initialize wallet mode.
-4. Verify auth status.
-5. Show wallet address.
+2. Configure environment (if not using production).
+3. Login.
+4. Initialize wallet mode.
+5. Verify auth status.
+6. Show wallet address.
 
 ## Check CLI Installation
 
 ```bash
 mm --version
 ```
 
-If this fails, the CLI is not installed. Guide the user to install it before proceeding.
+If this fails, the CLI is not installed. Guide the user to install it with `npm install -g @metamask/agentic-cli@latest` before proceeding.
+
+Then run the version compatibility check from the skill `Preflight` section: compare the installed `major.minor` against the pinned `cliVersion` and the latest published release, and warn the user if they are out of sync.
+
+## Configure Environment
+
+Production (`prod`) is the default. Set the target environment **before** login if the user needs dev or uat:
+
+```bash
+mm config get env
+mm config set env dev
+```
+
+For a one-off override without persisting, use `MM_ENV=dev mm login` (or `uat`).
+
+To switch environments, run `mm config set env <prod|dev|uat>`.
 
 ## Login Flow
 
@@ -49,7 +65,11 @@ First check if the project is already initialized:
 mm init show
 ```
 
-If already initialized, skip this step. Otherwise, ask the user which wallet mode they want:
+If already initialized, skip this step.
+
+For server-wallet mode, if the account already has a remote wallet, `mm init` syncs it and reuses the existing trading mode — no trading-mode prompt.
+
+Otherwise, ask the user which wallet mode they want:
 - `server-wallet` (recommended) — keys are hosted by MetaMask infrastructure. No need to manage private keys or mnemonics.
 - `byok` — bring your own mnemonic. The user manages their own keys locally.
 

skills/metamask-agent-workflows/workflows/troubleshooting.md

@@ -8,6 +8,7 @@ Run or suggest these in order:
 
 ```bash
 mm --version
+mm config get env
 mm auth status
 mm <failing-command> --help
 ```
@@ -20,7 +21,7 @@ If `auth status` reports anything other than authenticated, fix authentication b
 | --- | --- | --- |
 | `mm: command not found` | Binary not installed or not on `PATH` | Check install and PATH |
 | Async command returns a polling id and appears stuck | Request was dispatched without `--wait` | Use `mm wallet requests list` or `mm wallet requests watch --polling-id <id>` |
-| Auth errors after previously working | Expired token or wrong environment | Check `mm auth status` and environment/session file |
+| Auth errors after previously working | Expired token or wrong environment | Check `mm config get env`, `mm auth status`, and the env-scoped session file under `~/.metamask/` |
 | `CHAIN_ID_MISMATCH` on typed data | Payload `domain.chainId` differs from `--chain-id` | Align the two chain IDs |
 | `MNEMONIC_LOCKED` or `WRONG_PASSWORD` | BYOK mnemonic is encrypted and password was wrong or missing | Set the correct `MM_PASSWORD` environment variable and re-run |
 | `ALREADY_ENCRYPTED` on `wallet password set` | Mnemonic already has a password | Use `mm wallet password change` instead |