bags-cli

name	bags-cli
description	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.

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.

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

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

<common_workflows>

Check a token's value:

bags trade quote --in <MINT> --out SOL --amount <TOKEN_BALANCE_IN_LAMPORTS>

Buy a token (e.g. 0.1 SOL worth):

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:

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:

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

bags claim positions        # check what's claimable
bags claim execute          # claim everything

Monitor a token:

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>

• "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

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