# Bags CLI

> Expert operator of the `bags` CLI tool for Bags.fm. Use when Lex asks you to interact with the Bags API — launch tokens, swap, claim fees, check prices, manage wallets, or any Bags platform operation. You execute commands directly, not just advise.

- Skill: `glittercowboy/bags-cli` (Agent Skill)
- Install (CLI): `npx skillmds@latest add glittercowboy/bags-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/glittercowboy/bags-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: glittercowboy (https://skillmd.com/u/glittercowboy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/glittercowboy/bags-cli

---


<objective>
You are an expert operator of the `bags` CLI installed globally. When Lex asks you to do anything on the Bags platform, you use this CLI to do it. You don't explain how — you just do it.
</objective>

<critical_rules>

- **ALWAYS run `bags <command>`** — it is installed globally via `npm link`. NEVER use `npx tsx bin/bags.ts` or `npx tsx src/cli.ts` or `node dist/index.js`. Just `bags`.
- **To check token holdings**, use `spl-token accounts --owner Df5c7cSni29vo4hqy3dqhaMQHjnauRRCWGyDhryj967v` — NOT `bags wallet list` (that requires Moltbook JWT auth which is not set up).
- **To check SOL balance**, use `solana balance Df5c7cSni29vo4hqy3dqhaMQHjnauRRCWGyDhryj967v`.
- **`bags wallet list/export` and `bags keys list/create` require Moltbook JWT auth** — these will fail unless `bags auth init` + `bags auth login` have been completed. They are separate from the API key.
- If the CLI isn't responding or commands fail with module errors, rebuild: `cd /Users/lexchristopherson/Developer/bags-app/cli-bags && npm run build`

</critical_rules>

<domain_knowledge>

**Bags.fm** is a Solana token launch platform. Creators launch tokens, and every trade generates fees that flow to configurable claimers (creators, partners, etc.).

**Token lifecycle**: PRE_LAUNCH → PRE_GRAD (trading on virtual pool) → MIGRATING → MIGRATED (graduated to DAMM v2 pool with full liquidity).

**Fee sharing**: When a token is launched, a fee share config defines who earns trading fees. Up to 100 claimers, each assigned basis points (BPS). Total BPS must equal exactly 10000 (100%). Supported social providers for claimer lookup: twitter, tiktok, kick, github.

**Partner program**: Partners earn a cut of platform fees on tokens launched with their partner key. Separate from fee sharing.

**Incorporation**: Legal entity formation for token projects. Paid service through Bags.

**Pools**: Tokens start on Meteora DBC (Dynamic Bonding Curve) virtual pools. After enough volume, they migrate to DAMM v2 with full AMM liquidity.

</domain_knowledge>

<essential_knowledge>

**Config**: `~/.bags/config.json` — API key, RPC URL, private key (base58), commitment level.
Keypair file: `~/.bags/keypair.json`
Wallet: `Df5c7cSni29vo4hqy3dqhaMQHjnauRRCWGyDhryj967v`

**Global flags** (work on any command):
- `--json` — machine-readable JSON output
- `--profile <name>` — use a named config profile
- `--dry-run` — sign transactions but don't submit (all tx-producing commands)

**Unit conversions**:
- 1 SOL = 1,000,000,000 lamports
- All `--amount` flags take lamports unless stated otherwise
- `--initial-buy` takes SOL (not lamports)
- `--slippage` and `--bps` are in basis points (1 bps = 0.01%, 100 bps = 1%)
- Use `SOL` as shorthand for the wrapped SOL mint in `--in`/`--out` flags

**Quick math**:
- 0.001 SOL = 1,000,000 lamports
- 0.01 SOL = 10,000,000 lamports
- 0.1 SOL = 100,000,000 lamports
- 1 SOL = 1,000,000,000 lamports

**Rate limit**: 1000 requests/hour across all keys on the account.

</essential_knowledge>

<safety_rules>

- **Always dry-run first** on swaps over 0.1 SOL or any token launch
- **Check balance** before swaps: `solana balance Df5c7cSni29vo4hqy3dqhaMQHjnauRRCWGyDhryj967v`
- **Check token holdings** before selling: `spl-token accounts --owner Df5c7cSni29vo4hqy3dqhaMQHjnauRRCWGyDhryj967v`
- **Get a quote first** before executing a swap to show Lex what he'll get
- **Confirm with Lex** before any live transaction that spends SOL
- **Never display private keys** on screen — the CLI redacts them in `config show` but raw config reads will expose them

</safety_rules>

<commands>

**Setup & Config**
- `bags config init` — interactive setup wizard
- `bags config set <key> <value>` — keys: api-key, rpc-url, private-key, commitment, active-profile
- `bags config show` — show config (secrets redacted)
- `bags ping` — health check

**Token Queries**
- `bags token leaderboard` — top tokens by lifetime fees
- `bags token feed` — browse recent token launches
- `bags token fees --mint <addr>` — lifetime fees for a token
- `bags token creators --mint <addr>` — list creators/fee claimers

**Token Launch** (multi-step: metadata → fee share config → launch tx)
- `bags token info --name X --symbol X --description X --image ./path.png` — create metadata only
- `bags token launch --name X --symbol X --description X --image ./path.png --claimers '[{"wallet":"...","bps":10000}]' --initial-buy 0.1` — full launch
  - Optional: `--twitter <url>`, `--website <url>`, `--telegram <url>`, `--partner <addr>`, `--tip <lamports>`, `--image-url <url>` (instead of --image)

**Trading**
- `bags trade quote --in SOL --out <mint> --amount <lamports>` — get swap quote
- `bags trade swap --in SOL --out <mint> --amount <lamports>` — execute swap
  - Optional: `--slippage <bps>`

**Fee Claiming**
- `bags claim positions [--wallet <addr>]` — list claimable fees
- `bags claim execute [--wallet <addr>]` — claim all fees (signs + sends)
- `bags claim stats --mint <addr>` — per-creator claim stats
- `bags claim events --mint <addr> [--limit N] [--offset N]` — claim history
  - Time-range mode: `--from <unix> --to <unix>` (replaces limit/offset)

**Fee Share Management**
- `bags fee-share list [--wallet <addr>]` — tokens where wallet is admin
- `bags fee-share lookup --username X --provider twitter` — find wallet by social
- `bags fee-share lookup-bulk --items '[{"username":"X","provider":"twitter"}]'`
- `bags fee-share create --mint <addr> --claimers '[{"wallet":"...","bps":5000}]'`
- `bags fee-share update --mint <addr> --claimers '<json>'`
- `bags fee-share transfer --mint <addr> --new-admin <addr>`

**Partner Program**
- `bags partner config [--wallet <addr>]` — get partner config
- `bags partner stats [--wallet <addr>]` — claimed/unclaimed fees
- `bags partner create` — create partner config (tx)
- `bags partner claim` — claim partner fees (tx)

**Pool Data**
- `bags pool leaderboard` — top tokens by fees
- `bags pool list [--migrated]` — all Bags pools
- `bags pool info --mint <addr>` — pool details for a token
- `bags pool config --vaults <addr,...>` — config keys by vault addresses

**Transactions**
- `bags tx send --tx <base58>` — send a signed transaction
- `bags tx bundle --txs <base58,...> [--region <region>]` — send Jito bundle
- `bags tx bundle-status --ids <id,...>` — check bundle status
- `bags tx jito-fees` — current Jito tip fee levels

**Dexscreener**
- `bags dex check --mint <addr>` — check order availability
- `bags dex order --mint <addr> --description X --icon-url X --header-url X [--links '<json>'] [--pay-with-sol]`
- `bags dex pay --order-uuid <uuid> --signature <sig>`

**Incorporation**
- `bags incorporate start-payment [--pay-with-sol]` — initiate payment
- `bags incorporate submit --details '<json>'` — submit details
- `bags incorporate start --token <addr>` — trigger process
- `bags incorporate details --token <addr>` — get project details
- `bags incorporate list` — list all projects

**Auth & Keys** (requires Moltbook account + JWT)
- `bags auth init --username <moltbook>` — start auth flow
- `bags auth login --identifier X --secret X --post-id X` — complete auth
- `bags keys list` — list API keys
- `bags keys create --name X` — create API key
- `bags wallet list` — list wallets
- `bags wallet export --address <addr>` — export private key

</commands>

<common_workflows>

**Check a token's value**:
```bash
bags trade quote --in <MINT> --out SOL --amount <TOKEN_BALANCE_IN_LAMPORTS>
```

**Buy a token** (e.g. 0.1 SOL worth):
```bash
bags trade quote --in SOL --out <MINT> --amount 100000000    # preview first
bags trade swap --in SOL --out <MINT> --amount 100000000     # execute
```

**Sell all of a token**:
```bash
spl-token accounts --owner Df5c7cSni29vo4hqy3dqhaMQHjnauRRCWGyDhryj967v  # get balance
bags trade quote --in <MINT> --out SOL --amount <FULL_BALANCE>             # preview
bags trade swap --in <MINT> --out SOL --amount <FULL_BALANCE>              # execute
```

**Launch a token with fee sharing**:
```bash
# 1. Look up claimer wallets by social handle
bags fee-share lookup --username <handle> --provider twitter

# 2. Launch (BPS must sum to 10000)
bags token launch --name "Name" --symbol "TICK" --description "Desc" \
  --image ./logo.png \
  --claimers '[{"wallet":"<ADDR>","bps":10000}]' \
  --initial-buy 0.1 \
  --twitter https://x.com/handle \
  --website https://site.com
```

**Claim all fees**:
```bash
bags claim positions        # check what's claimable
bags claim execute          # claim everything
```

**Monitor a token**:
```bash
bags token fees --mint <ADDR>           # total fees generated
bags token creators --mint <ADDR>       # who gets fees
bags claim stats --mint <ADDR>          # who has claimed what
bags pool info --mint <ADDR>            # pool details + migration status
```

**Check wallet balance**: `solana balance Df5c7cSni29vo4hqy3dqhaMQHjnauRRCWGyDhryj967v`

**Check token holdings**: `spl-token accounts --owner Df5c7cSni29vo4hqy3dqhaMQHjnauRRCWGyDhryj967v`

</common_workflows>

<known_tokens>

- **GSD** (Get Shit Done): `8116V1BW9zaXUM6pVhWVaAduKrLcEBi3RGXedKTrBAGS` — Lex's primary token, #9 on leaderboard
- **PTSD** (Post Trench Stress Disorder): `wNZL7ixpAhVLR5LTfUE3DZhjjZY6CGk5vhkknV2BAGS` — launched as CLI test, 100% fees to MrShempi

</known_tokens>

<known_quirks>

- `bags claim stats` bypasses the SDK (SDK bug) — uses raw `BagsApiClient` instead
- `bags partner claim` may return duplicate transactions from the API — second tx can fail with "already processed" (not a CLI bug)
- Fee claiming uses legacy `Transaction` (not `VersionedTransaction`)
- `--twitter` on token launch requires **full URL** (`https://x.com/handle`), not just the handle
- Ping endpoint is at `https://public-api-v2.bags.fm/ping` (root), not under `/api/v1/`
- Token amounts have 9 decimal places (same as SOL) — multiply display amount by 1e9 for lamports
- The initial buy in `token launch` is atomic with pool creation — no one can frontrun it

</known_quirks>

<troubleshooting>

- **"API key not set"** → `bags config set api-key <key>`
- **"RPC URL not set"** → `bags config set rpc-url https://api.mainnet-beta.solana.com`
- **"Private key not set"** → `bags config set private-key <base58-key>`
- **"Rate limited"** → wait, 1000 req/hr limit
- **"Invalid public key input"** → bad mint/wallet address, check for typos
- **API 500 on partner create** → wallet likely needs SOL funding
- **"Transaction simulation failed: already processed"** → API returned a duplicate tx, first one succeeded
- **Swap fails** → check balance is sufficient, try with `--slippage 500` for volatile tokens
- **Token launch fails at step 2** → fee share config issue, check BPS sum = 10000 and all wallet addresses are valid
- **Command not found: bags** → `cd /Users/lexchristopherson/Developer/bags-app/cli-bags && npm run build && npm link`

</troubleshooting>

<codebase_location>
`/Users/lexchristopherson/Developer/bags-app/cli-bags/`

Rebuild: `cd /Users/lexchristopherson/Developer/bags-app/cli-bags && npm run build`

Dev mode (no build needed): `npx tsx bin/bags.ts <command>`
</codebase_location>