Capital Staking Squads CLI

Custom CLI for managing Solana program upgrades through Squads multisig.

Setup

# Install dependencies
npm install

# Copy environment file and configure
cp .env.example .env

# Build
npm run build

# Link globally (optional)
npm link

Configuration

You can configure the CLI using environment variables or the built-in config manager.

Using Config Manager (Recommended)

# Add a new squad configuration
cs-squads config add my-squad

# List all configured squads
cs-squads config list

# Switch active squad
cs-squads config pick my-squad

# Show current configuration
cs-squads config show

Using Environment Variables

Edit .env with your values:

SOLANA_RPC="https://api.devnet.solana.com"
SQDS_MULTISIG="<your-multisig-address>"
SIGNER="path/to/signer.json"
PROGRAM_SO_PATH="./target/deploy/program.so"
PROGRAM_BUFFER="<buffer-address>"
PROGRAM_ID="<program-to-upgrade>"

Usage

# Show help
cs-squads --help

# Or if not linked globally
node dist/index.js --help

Commands

squad - View & Manage Your Squad

Interactive mode to view squad info and manage vault funds.

# Interactive mode (default)
cs-squads squad

# Show squad info, members, and vault balance
cs-squads squad show

# Deposit SOL to the vault
cs-squads squad deposit 1.5

# Create a proposal to withdraw SOL
cs-squads squad withdraw 0.5 --recipient <ADDRESS> --auto-approve

| Option | Description | |--------|-------------| | -m, --multisig | Multisig address (or use active config) | | -s, --signer | Path to signer keypair JSON |

Withdraw options: | Option | Description | |--------|-------------| | -r, --recipient | Recipient address (default: signer) | | --auto-approve | Auto-approve after creating proposal |

proposals - Manage Proposals

Interactive mode to view, vote on, and execute proposals.

# Interactive mode (default) - browse and manage proposals
cs-squads proposals

# Non-interactive commands for scripting
cs-squads proposals list
cs-squads proposals show 5
cs-squads proposals approve 5
cs-squads proposals reject 5
cs-squads proposals execute 5

| Option | Description | |--------|-------------| | -m, --multisig | Multisig address (or use active config) | | -s, --signer | Path to signer keypair JSON | | -a, --all | Show all proposals (list command) | | -l, --limit | Number of recent proposals to show |

Features:

• Interactive proposal selector with status and vote count
• Detailed proposal view with decoded instructions
• Permission-gated actions (Vote, Execute)
• Confirmation prompts for all actions

config - Manage Squad Configurations

Store multiple squad configurations and switch between them.

cs-squads config show      # Show current configuration
cs-squads config list      # List all configured squads
cs-squads config pick      # Switch active squad (interactive)
cs-squads config add NAME  # Add a new squad configuration
cs-squads config edit NAME # Edit an existing configuration
cs-squads config remove NAME # Remove a configuration
cs-squads config path      # Show config file location
cs-squads config validate  # Validate current configuration

propose-upgrade - Program Upgrades

Propose a program upgrade through the Squads multisig.

# One command does it all (upload, set authority, propose)
cs-squads propose-upgrade \
  --program-path ./target/deploy/program.so \
  --program-id <PROGRAM_ID> \
  --auto-approve

# Or with existing buffer
cs-squads propose-upgrade \
  --buffer <BUFFER_ADDRESS> \
  --program-id <PROGRAM_ID>

| Option | Description | |--------|-------------| | -p, --program-id | Program ID to upgrade | | -f, --program-path | Path to .so file - auto-uploads buffer and sets authority | | -b, --buffer | Buffer address containing new program | | -m, --multisig | Squads multisig address | | -s, --signer | Path to signer keypair JSON | | -v, --vault-index | Vault index (default: 0) | | --memo | Optional memo for the proposal | | --auto-approve | Auto-approve after creating proposal |

write-buffer - Upload Program

Upload a compiled program (.so file) to a buffer account.

cs-squads write-buffer --program-path ./target/deploy/program.so

| Option | Description | |--------|-------------| | -f, --program-path | Path to .so file (or PROGRAM_SO_PATH env) | | -s, --signer | Signer keypair (or SIGNER env) | | --buffer-keypair | Optional: use specific keypair for buffer address |

set-buffer-authority - Transfer Buffer Authority

Transfer buffer authority to Squads vault (or another address).

cs-squads set-buffer-authority --buffer <BUFFER>

| Option | Description | |--------|-------------| | -b, --buffer | Buffer address (or PROGRAM_BUFFER env) | | -a, --new-authority | New authority address (default: vault PDA) | | -m, --multisig | Multisig address (or SQDS_MULTISIG env) | | -v, --vault-index | Vault index (default: 0) | | -s, --signer | Current authority keypair (or SIGNER env) |

Program Upgrade Workflow

1. Build your program

   anchor build
   # or
   cargo build-sbf

2. Propose the upgrade (one command does it all)

   cs-squads propose-upgrade \
     --program-path ./target/deploy/program.so \
     --program-id <PROGRAM_ID> \
     --auto-approve

   This automatically: uploads buffer, sets authority to vault, creates proposal, and approves.

3. Other members approve

   cs-squads proposals approve <INDEX>

4. Execute once threshold is met

   cs-squads proposals execute <INDEX>

Step-by-Step Workflow (Alternative)

If you prefer more control, run each step separately:

1. Upload to buffer

   cs-squads write-buffer --program-path ./target/deploy/program.so
   # Outputs: Buffer address: <BUFFER>

2. Transfer buffer authority to Squads vault

   cs-squads set-buffer-authority --buffer <BUFFER>
   # Outputs: Authority transferred to vault: <VAULT>

3. Propose the upgrade

   cs-squads propose-upgrade --buffer <BUFFER> --program-id <PROGRAM_ID>

Project Structure

src/
├── index.ts                    # CLI entry point
├── commands/
│   ├── index.ts                # Command exports
│   ├── config.ts               # Config management commands
│   ├── proposals.ts            # Proposal management commands
│   ├── squad.ts                # Squad info & fund management
│   ├── propose-upgrade.ts      # Propose upgrade command
│   ├── write-buffer.ts         # Write buffer command
│   └── set-buffer-authority.ts # Set authority command
└── utils/
    ├── connection.ts           # RPC & keypair helpers
    ├── config.ts               # Config file management
    ├── squads.ts               # Squads multisig helpers
    ├── instruction-decoder.ts  # Decode known instructions
    └── bpf-loader.ts           # BPF Upgradeable Loader utilities

Available Utilities

Connection utilities (src/utils/connection.ts)

• getConnection() - Get RPC connection from env/config
• loadKeypair(path?) - Load keypair from file
• getMultisig(cliOption?) - Get multisig address from CLI/env/config
• getVaultIndex(cliOption?) - Get vault index from CLI/config

Squads utilities (src/utils/squads.ts)

• getMultisigInfo(connection, multisigPda) - Fetch multisig account
• getNextTransactionIndex(connection, multisigPda) - Get next tx index
• getVaultPda(multisigPda, vaultIndex) - Derive vault PDA
• getProposalPda(multisigPda, transactionIndex) - Derive proposal PDA
• getMemberPermissions(multisigAccount, memberPubkey) - Check member permissions
• buildVaultTransactionCreateInstruction(params) - Build vault tx instruction
• buildProposalCreateInstruction(...) - Build proposal create instruction
• buildProposalApproveInstruction(...) - Build proposal approve instruction
• buildProposalRejectInstruction(...) - Build proposal reject instruction

Known Limitations

Program Size Extension

The BPF Loader's ExtendProgram instruction cannot be executed via Squads CPI. If your new program binary is larger than the existing ProgramData account capacity, the CLI will abort with an error and instructions.

Workarounds:

1. Deploy programs with extra space using --max-len:

   solana program deploy program.so --max-len <size>

2. If you need to extend a program already under Squads authority:

   • Transfer authority to a keypair temporarily
   • Extend the program: solana program extend <PROGRAM_ID> <BYTES>
   • Transfer authority back to the Squads vault
   • Then propose the upgrade

Roadmap

Planned features for future releases:

program-return-authority

Transfer program upgrade authority away from Squads vault back to a keypair. Useful for emergency situations or when program extension is required.

# Planned usage
cs-squads program-return-authority \
  --program-id <PROGRAM_ID> \
  --new-authority <KEYPAIR_ADDRESS>

Proposal Verification

Safety features for reviewing proposals before voting:

• Verify buffer contents match expected program hash
• Compare against local .so file
• Show simulation results before execution