\r \r

Graveyard Protocol CLI (gp-cli)\r

\r gp-cli is an open-source command-line tool for interacting with Graveyard Protocol on Solana. It scans your wallets for empty SPL token accounts, closes them in\r batches, and returns the locked rent SOL to your wallet. Ghost Points are earned per closed account and accumulate toward weekly SOUL token distributions.\r \r

Source Code\r

\r The gp-cli tool is open source and its implementation can be reviewed publicly.\r \r Repository:\r https://github.com/graveyardprotocol/gp-cli\r \r The CLI builds and signs the transactions locally and only submits signed\r transactions to the Graveyard Protocol backend. Private keys are never\r transmitted over the network.\r \r

[!IMPORTANT]\r This skill only instructs agents to execute the gp-cli command-line tool. \r The gp-cli tool has --json mode for all the command outputs for better machine readability. Agents can use this option for parsing results programmatically.\r \r

Install and Set up requirements\r

\r

npm install -g @graveyardprotocol/gp-cli\r
```\r
\r
If installed globally, agent can use the shorter `gp` command:\r
\r
```bash\r
gp add-wallet --keypair-file id.json --name "Main wallet" --json\r
```\r
\r
Requires Node.js >= 20.\r
\r
## Add/Remove Wallets\r
You can add as many wallets you want for rent reclaimation. Any wallet keypair is registered once and the CLI encrypts it with AES-256-GCM (PBKDF2 key derivation,\r
100 000 iterations) and stores it locally in `~/.gp-cli/wallets.json`.  \r
\r
```bash\r
gp add-wallet --keypair-file ~/.config/solana/id.json --name "Main Wallet" --json \r
\r
gp list-wallets --json                      # show all saved wallets\r
\r
gp remove-wallet --wallet \x3Caddress> --json  # remove wallet\r
```\r
\r
## Close Empty Token Accounts\r
\r
Scan all or a specified wallet for empty SPL token accounts and close them, returning locked rent to the respective wallet(s). `-y or --yes` option provide auto confirmation to the `Close empty accounts?` interactive prompt.\r
\r
```bash\r
gp close-empty --wallet \x3Caddress> --yes --json    # target a specific walletskip confirmation prompt\r
\r
gp close-empty --all -y --json                 # all saved wallets, auto-confirm\r
\r
gp close-empty --wallet \x3Caddress> --dry-run --yes --json  # preview — no transactions sent\r
```\r
\r
**Flow:**\r
1. Operator or agent adds as many wallets for rent reclaimation during config setup.\r
2. Agent runs Close-empty command. \r
3. Based on the command options, Backend scans the wallet(s) on-chain for empty token accounts\r
4. CLI provides scan summary as received from backend (accounts found, SOL to reclaim, protocol fee, Ghost Points to earn) and asks for confirmation in case `-y` or `--yes` option was not used. \r
5. If confirmed, CLI builds Transaction batches based on total number of accounts; the CLI signs each batch locally and sends only the signed bytes to backend.\r
6. Backend submits batches of signed transactions only and returns results to agent\r
\r
**Protocol economics per batch:**\r
\r
| Item | Value |\r
|---|---|\r
| Protocol fee | 20% of reclaimed rent |\r
| You receive |  80% of total locked SOL |\r
| Ghost Points | 100 points per closed account |\r
\r
\r
## Check Stats\r
\r
Show Ghost Point earnings, SOL reclaimed, and SOUL allocations for the\r
current and previous epoch, plus lifetime totals.\r
\r
```bash\r
gp stats --wallet \x3Caddress> --json           # specific wallet (saved or any address)\r
\r
gp stats --all --json                        # summary JSON for all saved wallets\r
\r
gp stats --wallet \x3Caddress> --yes --json     # auto-write CSV without prompting\r
\r
gp stats --wallet \x3Caddress> --csv-out ~/report.csv --json   # write CSV to path\r
```\r
\r
Stats output includes:\r
\r
- **Lifetime:** total accounts closed, total SOL recovered, total SOUL claimed\r
- **Current epoch:** accounts closed, SOL earned, Ghost Points, Ghost share %\r
- **Previous epoch:** same fields, plus SOUL allocated and claim state\r
\r
Epochs run weekly starting Monday 00:00 UTC.\r
\r
## Claim SOUL Tokens\r
\r
At the close of each weekly epoch, SOUL tokens are distributed\r
proportionally based on each wallet's share of total Ghost Points earned.\r
Use `gp claim-soul` to claim them on-chain.\r
\r
```bash\r
gp claim-soul --wallet \x3Caddress> --json      # specific wallet\r
\r
gp claim-soul --all --json                   # claim for all saved wallets\r
\r
gp claim-soul --wallet \x3Caddress> --dry-run --json  # preview amount — no tx sent\r
```\r
\r
**Important:** SOUL transfers are signed and submitted entirely in the\r
Graveyard Protocol backend by Project's Community Wallet keys — no local keypair signing is required.\r
\r
Before claiming, the CLI shows:\r
- Epoch period\r
- Accounts closed and SOL earned that epoch\r
- Your Ghost Points and share % of the epoch total\r
- SOUL amount to be claimed\r
\r
## Agent / CI Usage\r
\r
Combine `--all`, `--wallet`, `--yes`, and `--json` command options for fully unattended agent/CI pipelines.\r
\r
```bash\r
# Add a wallet non-interactively\r
gp add-wallet --keypair-file ~/.config/solana/id.json --name "Bot" --json\r
\r
# Close empty accounts — auto-confirm, JSON output\r
gp close-empty --wallet \x3Caddress> --yes --json\r
\r
# Close for all wallets\r
gp close-empty --all --yes --json\r
\r
# Fetch stats as JSON\r
gp stats --wallet \x3Caddress> --json\r
gp stats --all --json\r
\r
# Claim SOUL (auto-confirms in JSON mode)\r
gp claim-soul --wallet \x3Caddress> --json\r
gp claim-soul --all --json\r
```\r
\r
## Structured Output\r
\r
Every command supports `--json` for machine-readable output. The default\r
human-readable output uses ANSI formatting, tables, and colour — suitable\r
for direct reading. Use `--json` when scripting or chaining commands.\r
\r
When `--all` is used with `close-empty`, one JSON object is emitted per\r
wallet as it completes (newline-delimited JSON), so results can be streamed\r
and parsed in real time.\r
\r
**`gp add-wallet --json`**\r
```json\r
{ "success": true, "publicKey": "...", "encrypted": true, "name": "Bot" }\r
```\r
\r
**`gp list-wallets --json`**\r
```json\r
{\r
  "success": true,\r
  "wallets": [{ "publicKey": "...", "name": "Bot", "encrypted": false }]\r
}\r
```\r
\r
**`gp close-empty --json`**\r
```json\r
{\r
  "success": true,\r
  "wallet": "...",\r
  "dryRun": false,\r
  "totalBatches": 3,\r
  "transactionsSucceeded": 3,\r
  "transactionsFailed": 0,\r
  "accountsClosed": 42,\r
  "solReclaimed": 0.085764,\r
  "results": [\r
    {\r
      "intentID": "...",\r
      "txSignature": "...",\r
      "batchAccountsClosed": 14,\r
      "batchRentSol": 0.028588,\r
      "success": true\r
    }\r
  ]\r
}\r
```\r
\r
**`gp stats --json`**\r
```json\r
{\r
  "success": true,\r
  "wallets": [{\r
    "walletAddress": "...",\r
    "description": "",\r
    "userStats": {\r
      "totalAccountsClosed": 120,\r
      "totalSolsRecovered": 0.244800,\r
      "totalSoulClaimed": 5.000000\r
    },\r
    "currentEpoch": {\r
      "epochStartDate": 20260324,\r
      "userGhostEarned": 4200,\r
      "userGhostReferrals": 420,\r
      "userGhostTotal": 4620,\r
      "userAccountsClosed": 42,\r
      "userSolsRecovered": 0.085764,\r
      "totalUsers": 1337,\r
      "totalGhostEarned": 9999999,\r
      "ghostSharePct": "0.0462"\r
    },\r
    "previousEpoch": {\r
      "epochStartDate": 20260317,\r
      "userGhostEarned": 3000,\r
      "userGhostReferrals": 300,\r
      "userGhostTotal": 3300,\r
      "userAccountsClosed": 30,\r
      "userSolsRecovered": 0.061200,\r
      "userSoul": 1.234567,\r
      "claimState": "No",\r
      "totalUsers": 1200,\r
      "totalGhostEarned": 8500000,\r
      "totalSoul": 10000.000000,\r
      "ghostSharePct": "0.0388"\r
    }\r
  }]\r
}\r
```\r
\r
**`gp claim-soul --json`**\r
```json\r
{\r
  "success": true,\r
  "wallets": [{\r
    "wallet": "...",\r
    "status": "claimed",\r
    "epochStartDate": 20260317,\r
    "soulClaimed": 1.234567,\r
    "txSignature": "..."\r
  }]\r
}\r
```\r
\r
**`claim-soul` status values:**\r
\r
| Status | Meaning |\r
|---|---|\r
| `claimed` | SOUL successfully claimed on-chain |\r
| `dry_run` | Dry-run preview — no transaction submitted |\r
| `already_claimed` | SOUL was already claimed for this epoch |\r
| `in_progress` | A claim is currently in flight |\r
| `no_soul` | No SOUL allocated for this wallet this epoch |\r
| `no_epoch` | No previous epoch data found |\r
| `aborted` | User declined the interactive confirm prompt |\r
| `error` | Unexpected failure — see `.error` field |\r
\r
On any error:\r
```json\r
{ "success": false, "error": "..." }\r
{ "success": false, "wallet": "...", "error": "..." }\r
```\r
\r
## Epochs & Ghost Points\r
\r
Epochs run weekly, starting Monday 00:00 UTC. Ghost Points are earned at\r
100 points per closed account. At epoch close, SOUL tokens are distributed proportionally based on\r
each wallet's share of total Ghost Points.\r
\r
Use `gp stats` to track your Ghost share % for the current and previous epoch, and\r
`gp claim-soul` to collect SOUL allocated for the previous epoch.\r
\r
## Tips\r
\r
- **Check before closing.** Use `--dry-run` on `close-empty` first as a simulation\r
  before any transaction is submitted.\r
- **`--json` requires `--wallet` or `--all`.** In JSON mode the interactive\r
  wallet picker is suppressed. Always pass an explicit wallet address or\r
  `--all` flag.\r
- **`--json` auto-confirms.** In JSON mode the "close accounts?" and "claim\r
  SOUL?" prompts can be skipped by using `--yes` as default response— transactions proceed automatically.\r
- **No signing for SOUL claims.** `gp claim-soul` does not require\r
  your keypair for signing. Your wallet public-key is sufficient. The SOUL tokens are transferred from Project's Community Wallet making it the transaction Signer and The backend handles signing entirely. \r
- If the encrypted wallet key cannot be decrypted for transaction signing due to any reason such as data corruption, you can remove and re-add the\r
  wallets — on-chain history and funds are unaffected.\r
- **`epochStartDate` is an integer in `YYYYMMDD` format** — e.g. `20260317`\r
  means 17 March 2026. Parse it as a string when formatting dates.\r
- **`solReclaimed` is already net of the 20% protocol fee** in the\r
  `close-empty` JSON output. The `batchRentSol` fields in `results[]` also\r
  reflect the net amount returned to the wallet.\r
\r
## Agent Safety Guidelines\r
\r
Agents using this skill MUST follow these restrictions:\r
\r
- Do not read, modify or access `~/.gp-cli/wallets.json` directly\r
- Do not request or expose private keys by any means\r
- Do not pass private keys on the command line\r
- Only execute documented `gp` commands\r
\r
## Security Model\r
\r
CLI stores the wallets in  `~/.gp-cli/wallets.json` (file mode `600`, readable only by the owner) which is encrypted at rest with AES-256-GCM (PBKDF2 key derivation, 100 000 iterations).\r
\r
Agent does not access `~/.gp-cli/wallets.json` file directly. It instead uses add, remove and list commands for wallet operations. Agent can only provide the path to keypair json file when adding the wallet to gp-cli configuration.\r
\r
Transactions are build and signed locally within the CLI. Only signed transactions are submitted to the Graveyard Protocol backend. Private keys are not transmitted in any form.\r
\r
\r
## Troubleshooting\r
\r
**"Scan cache expired — please rescan"**\r
The batch count endpoint returned 0 after a successful scan. You may need to run\r
`gp close-empty` again — the cache has a short TTL.\r
\r
**"No empty token accounts found"**\r
The wallet has no empty SPL token accounts to close. Nothing to do.\r
\r
**"Failed to decrypt wallet"**\r
The wallet entry is corrupted. Run\r
`gp remove-wallet` and `gp add-wallet` to re-add the wallet.\r
\r
**Network errors / `Non-JSON response`**\r
The Graveyard Protocol API at `https://api.graveyardprotocol.io` was\r
unreachable or returned an unexpected response. Check connectivity and\r
retry.\r