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 ```sh 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`: ```json { "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: ```bash gator init --profile <profile-name> gator create --profile <profile-name> ``` Grant an ERC-20 transfer delegation: ```bash gator grant --profile <profile-name> --to <to-address> --scope erc20TransferAmount \ --tokenAddress <token-address> --maxAmount 50 ``` Redeem an ERC-20 transfer: ```bash gator redeem --profile <profile-name> --from <from-address> --action erc20Transfer \ --tokenAddress <token-address> --to <to-address> --amount 10 ``` Redeem a native transfer: ```bash gator redeem --profile <profile-name> --from <from-address> --action nativeTransfer \ --to <to-address> --amount 0.5 ``` Redeem in raw mode: ```bash gator redeem --profile <profile-name> --from <from-address> --action raw \ --target <contract-address> --callData 0xa9059cbb... ``` Inspect delegations: ```bash gator inspect --profile <profile-name> gator inspect --profile <profile-name> --from <from-address> gator inspect --profile <profile-name> --to <to-address> ``` Revoke a delegation: ```bash 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`.