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/.json)
• Delegations local cache: ~/.gator-cli/delegations/.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 ] [--profile ]
• --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 ]
• 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 ]

status

Check config and on-chain account status.

• gator status [--profile ]
• 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 ] [--profile ]
• 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 --scope [scope flags] [--profile ]

Scope flags:

• Token scopes: --tokenAddress , --maxAmount , --tokenId
• Periodic scopes: --periodAmount , --periodDuration , --startDate
• Streaming scopes: --amountPerSecond , --initialAmount , --startTime
• Function call scope: --targets , --selectors , --valueLte
• Ownership transfer: --contractAddress

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 --action [action flags] [--profile ]

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 [--profile ]

inspect

Inspect delegations for your account.

• gator inspect [--from ] [--to ] [--profile ]
• 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 
gator create --profile 

Grant an ERC-20 transfer delegation:

gator grant --profile  --to  --scope erc20TransferAmount \
  --tokenAddress  --maxAmount 50

Redeem an ERC-20 transfer:

gator redeem --profile  --from  --action erc20Transfer \
  --tokenAddress  --to  --amount 10

Redeem a native transfer:

gator redeem --profile  --from  --action nativeTransfer \
  --to  --amount 0.5

Redeem in raw mode:

gator redeem --profile  --from  --action raw \
  --target  --callData 0xa9059cbb...

Inspect delegations:

gator inspect --profile 
gator inspect --profile  --from 
gator inspect --profile  --to 

Revoke a delegation:

gator revoke --profile  --to 

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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MetaMask
• Source: MetaMask/skills
• License: MIT

Install and usage instructions live in the source repository linked above.