gator-cli

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:

• --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

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.