gator-cli

name	gator-cli
description	Use when you need to operate the @metamask/gator-cli to initialize profiles, upgrade EOA to EIP-7702, grant, redeem, and revoke ERC-7710 delegations, or inspect balances and delegations. Covers commands, required flags, grant scopes, redeem action types, configuration locations, and common usage flows.

Quick Reference

Use this skill to run the gator CLI from the repo and to choose the correct command/flags for delegation workflows.

Installation

npm install -g @metamask/gator-cli

CLI Overview

• Binary name: gator
• Default profile: default
• Config path: ~/.gator-cli/permissions.json (or ~/.gator-cli/profiles/<profile-name>.json)
• Delegations local cache: ~/.gator-cli/delegations/<profile-name>.json when storage not configured

Configuration Requirements

Edit the profile config after gator init:

{
  "delegationStorage": {
    "apiKey": "your-api-key",
    "apiKeyId": "your-api-key-id"
  },
  "rpcUrl": "https://your-rpc-url.com"
}

• delegationStorage is optional; when missing, delegations are stored locally.
• rpcUrl is required for on-chain actions.

Commands

init

Generate a private key and save config. Errors if the profile already exists.

• gator init [--chain <chain>] [--profile <profile-name>]
• --chain values: base (default), baseSepolia, sepolia
• --profile default: default
• Prints: address, chain, and config file path.

create

Upgrade an EOA to an EIP-7702 smart account. Uses the chain in your profile config.

• gator create [--profile <profile-name>]
• Requires the account to be funded with native token first.
• Prints: address, chain, and the upgrade transaction hash.

show

Display the EOA address for a profile.

• gator show [--profile <profile-name>]

status

Check config and on-chain account status.

• gator status [--profile <profile-name>]
• Prints: address, chain, config upgrade status, on-chain code presence, storage and RPC URL config.

balance

Show native balance and optional ERC-20 balance.

• gator balance [--tokenAddress <address>] [--profile <profile-name>]
• If --tokenAddress is provided, prints ERC-20 balance and decimals-derived units.

grant

Create, sign, and store a delegation with a predefined scope.

• gator grant --to <to-address> --scope <type> [scope flags] [--profile <profile-name>]

Scope flags:

• Token scopes: --tokenAddress <token-address>, --maxAmount <amount>, --tokenId <id>
• Periodic scopes: --periodAmount <amount>, --periodDuration <seconds>, --startDate <timestamp>
• Streaming scopes: --amountPerSecond <amount>, --initialAmount <amount>, --startTime <timestamp>
• Function call scope: --targets <addresses>, --selectors <sigs>, --valueLte <ether>
• Ownership transfer: --contractAddress <contract-address>

Supported scopes:

• erc20TransferAmount
• erc20PeriodTransfer
• erc20Streaming
• erc721Transfer
• nativeTokenTransferAmount
• nativeTokenPeriodTransfer
• nativeTokenStreaming
• functionCall
• ownershipTransfer

Grant flags per scope:

Scope	Required Flags	Optional Flags
erc20TransferAmount	--tokenAddress, --maxAmount
erc20PeriodTransfer	--tokenAddress, --periodAmount, --periodDuration	--startDate
erc20Streaming	--tokenAddress, --amountPerSecond, --initialAmount, --maxAmount	--startTime
erc721Transfer	--tokenAddress, --tokenId
nativeTokenTransferAmount	--maxAmount
nativeTokenPeriodTransfer	--periodAmount, --periodDuration	--startDate
nativeTokenStreaming	--amountPerSecond, --initialAmount, --maxAmount	--startTime
functionCall	--targets, --selectors	--valueLte
ownershipTransfer	--contractAddress

• --startDate and --startTime default to the current time (unix seconds) when omitted.
• --valueLte sets the max native token value per call for functionCall scopes.

redeem

Redeem a stored delegation using a specific action type.

• gator redeem --from <from-address> --action <type> [action flags] [--profile <profile-name>]

Supported action types: erc20Transfer, erc721Transfer, nativeTransfer, functionCall, ownershipTransfer, raw

Action-specific flags:

• erc20Transfer: --tokenAddress, --to, --amount
• erc721Transfer: --tokenAddress, --to, --tokenId
• nativeTransfer: --to, --amount
• functionCall: --target, --function, --args, --value
• ownershipTransfer: --contractAddress, --to
• raw: --target, --callData, --value

revoke

Revoke a delegation on-chain. Revokes the first matching delegation.

• gator revoke --to <to-address> [--profile <profile-name>]

inspect

Inspect delegations for your account.

• gator inspect [--from <from-address>] [--to <to-address>] [--profile <profile-name>]
• With no filters, prints both Given and Received.
• Printed fields: From, To, Authority, Caveats count, Signed flag.

Redeem Flags per Action

Action	Required Flags
erc20Transfer	--tokenAddress, --to, --amount
erc721Transfer	--tokenAddress, --to, --tokenId
nativeTransfer	--to, --amount
functionCall	--target, --function, --args
ownershipTransfer	--contractAddress, --to
raw	--target, --callData

Example Flows

Initialize and upgrade:

gator init --profile <profile-name>
gator create --profile <profile-name>

Grant an ERC-20 transfer delegation:

gator grant --profile <profile-name> --to <to-address> --scope erc20TransferAmount \
  --tokenAddress <token-address> --maxAmount 50

Redeem an ERC-20 transfer:

gator redeem --profile <profile-name> --from <from-address> --action erc20Transfer \
  --tokenAddress <token-address> --to <to-address> --amount 10

Redeem a native transfer:

gator redeem --profile <profile-name> --from <from-address> --action nativeTransfer \
  --to <to-address> --amount 0.5

Redeem in raw mode:

gator redeem --profile <profile-name> --from <from-address> --action raw \
  --target <contract-address> --callData 0xa9059cbb...

Inspect delegations:

gator inspect --profile <profile-name>
gator inspect --profile <profile-name> --from <from-address>
gator inspect --profile <profile-name> --to <to-address>

Revoke a delegation:

gator revoke --profile <profile-name> --to <to-address>

Operational Notes

• Private key security: This is alpha version. Private keys are stored in plaintext JSON. Never use accounts with significant funds.
• --from refers to the delegator address; --to refers to the delegate/recipient.
• --targets and --selectors are comma-separated lists.
• --function accepts a human-readable Solidity function signature like "approve(address,uint256)". Do not pass a 4-byte selector (e.g. 0x095ea7b3) — the CLI derives the selector from the signature automatically.
• --startDate and --startTime accept unix timestamps in seconds. When omitted, they default to the current time.
• --action is required for redeem and must be one of: erc20Transfer, erc721Transfer, nativeTransfer, functionCall, ownershipTransfer, raw.
• Supported chains for --chain in gator init: base (default), baseSepolia, sepolia.