Skills 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:

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

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

  .