Shelby CLI Assistant

Shelby CLI Assistant

Purpose

Provide expert guidance on using the Shelby Protocol CLI tool for managing accounts, uploading/downloading blobs, configuring contexts (networks), and troubleshooting command-line operations.

When to Use

Auto-invoke when users mention:

• CLI Tool - Shelby CLI, @shelby-protocol/cli, command-line, terminal
• Commands - shelby upload, shelby download, shelby init, shelby account
• Operations - CLI upload, CLI download, account management, context setup
• Issues - CLI errors, troubleshooting, insufficient tokens, configuration
• Setup - Installation, initialization, funding, API keys

Knowledge Base

Shelby CLI documentation location:

.claude/skills/blockchain/aptos/docs/

Key files:

• tools_cli.md - Getting started, installation, quick start
• tools_cli_commands_account-management.md - Account operations
• tools_cli_commands_context-management.md - Network configuration
• tools_cli_commands_uploads-and-downloads.md - Upload/download commands
• tools_cli_commands_faucet.md - Token acquisition
• tools_cli_management.md - CLI management and updates

Installation & Setup

Installation

# npm
npm install -g @shelby-protocol/cli

# pnpm
pnpm add -g @shelby-protocol/cli

# yarn
yarn global add @shelby-protocol/cli

# bun
bun add -g @shelby-protocol/cli

Prerequisite: Node.js and npm must be installed.

Initialization

shelby init

What it does:

• Creates config file at ~/.shelby/config.yaml
• Prompts for API key (optional but recommended to avoid rate limits)
• Sets up default contexts (shelbynet and local)
• Creates default account
• Sets default context and account

Example config file:

contexts:
  shelbynet:
    aptos_network:
      name: shelbynet
      fullnode: https://api.shelbynet.shelby.xyz/v1
      faucet: https://faucet.shelbynet.shelby.xyz
      indexer: https://api.shelbynet.shelby.xyz/v1/graphql
    shelby_network:
      rpc_endpoint: https://api.shelbynet.shelby.xyz/shelby
  local:
    aptos_network:
      name: local
      fullnode: http://127.0.0.1:8080/v1
      faucet: http://127.0.0.1:8081
    shelby_network:
      rpc_endpoint: http://localhost:9090/

accounts:
  alice:
    private_key: ed25519-priv-0x8...
    address: "0xfcba...a51c"

default_context: shelbynet
default_account: alice

Account Management

Create Account

Interactive mode:

shelby account create

Non-interactive mode:

shelby account create \
  --name alice \
  --scheme ed25519 \
  --private-key ed25519-priv-0x... \
  --address 0x...

Options:

• --name <account-name> - Label for credentials
• --scheme <signature-scheme> - Currently supports ed25519
• --private-key <key> - Raw private key (ed25519-priv-0x… format)
• --address <aptos-address> - Aptos account address (0x…)

Note: All four flags required for non-interactive mode.

List Accounts

shelby account list

Output:

┌──────────────┬────────────────────────────────────────────────┬──────────────────┐
│ Name         │ Address                                        │ Private Key      │
├──────────────┼────────────────────────────────────────────────┼──────────────────┤
│ alice        │ 0xfcb......................................0fb │ ed25519-priv-0x8 │
│ (default)    │ c276e3e598938e00a51c                           │ adf5...          │
└──────────────┴────────────────────────────────────────────────┴──────────────────┘

Switch Account

shelby account use <ACCOUNT_NAME>

Example:

shelby account use alice
# ✅ Now using account 'alice'

Delete Account

shelby account delete <ACCOUNT_NAME>

Example:

shelby account delete bob
# ✅ Account 'bob' deleted successfully

Check Balance

shelby account balance

Output:

💰  Balance:

┌─────────┬───────────────────────────────────┬─────────────────────┬───────────────────┐
│ Token   │ Asset                             │ Balance             │ Raw Units         │
├─────────┼───────────────────────────────────┼─────────────────────┼───────────────────┤
│ APT     │ 0x1::aptos_coin::AptosCoin        │ 9.998885 APT        │ 999,888,500       │
├─────────┼───────────────────────────────────┼─────────────────────┼───────────────────┤
│ ShelbyU │ 0x1b18363a9f1fe5e6ebf247daba5cc1c │ 9.99993056          │ 999,993,056       │
│ SD      │ 18052bb232efdc4c50f556053922d98e1 │ ShelbyUSD           │                   │
└─────────┴───────────────────────────────────┴─────────────────────┴───────────────────┘

Options:

• -a, --account <name> - Query specific account
• -c, --context <name> - Use different context
• --address <hex> - Query raw Aptos address

List Blobs

shelby account blobs

Output:

📦  Stored Blobs
┌─────────────────────────────────────────────┬───────────────┬─────────────────────────┐
│ Name                                        │ Size          │ Expires                 │
├─────────────────────────────────────────────┼───────────────┼─────────────────────────┤
│ .gitignore-v1                               │ 494 B         │ Oct 11, 2025, 4:03 PM   │
└─────────────────────────────────────────────┴───────────────┴─────────────────────────┘

Options:

• -a, --account <name> - List blobs for specific account

Note: Requires Shelby indexer endpoint in context configuration.

Context Management

List Contexts

shelby context list

Output shows:

• Aptos configurations (fullnode, indexer, faucet)
• Shelby configurations (RPC endpoint)
• Default context marked with (default)

Create/Update Context

shelby context create <CONTEXT_NAME>
shelby context update <CONTEXT_NAME>

Switch Context

shelby context use <CONTEXT_NAME>

Funding Accounts

Required Tokens

1. APT - Aptos tokens for gas fees
2. ShelbyUSD - Tokens for storage and bandwidth

Get APT Tokens

Option 1: Faucet URL

shelby faucet --no-open  # Prints faucet URL
# Or remove --no-open to automatically open in browser

Option 2: Aptos CLI

# First configure aptos CLI
aptos init --profile shelby-alice \
  --assume-yes \
  --private-key ed25519-priv-0xa... \
  --network custom \
  --rest-url https://api.shelbynet.aptoslabs.com \
  --faucet-url https://faucet.shelbynet.shelby.xyz/

# Fund account
aptos account fund-with-faucet \
  --profile shelby-alice \
  --amount 1000000000000000000

Get ShelbyUSD Tokens

shelby faucet --no-open
# Visit the provided faucet URL to get ShelbyUSD tokens

Faucet URLs:

• APT: Via shelby faucet or Aptos CLI
• ShelbyUSD: https://faucet.shelbynet.shelby.xyz

Upload Operations

Basic Upload

shelby upload <src> <dst> -e <expiration>

Required:

• <src> - Local file path
• <dst> - Blob name in Shelby (max 1024 chars, no trailing /)
• -e, --expiration - Expiration timestamp

Example:

shelby upload local-video.mp4 videos/my-video.mp4 -e tomorrow
shelby upload ./file.txt data/file.txt --expiration "2025-12-31"
shelby upload document.pdf docs/doc.pdf -e 1735689600

Expiration Formats

Human-readable:

-e "tomorrow"
-e "in 2 days"
-e "next Friday"
-e "next month"
-e "2025-12-31"

Unix timestamp:

-e 1735689600  # Seconds since epoch

ISO date:

-e "2025-01-01T00:00:00Z"
-e "2025-01-01T00:00:00-0500"

Using date command (Unix):

shelby upload file.txt blob.txt -e $(date -d "+1 hour" +%s)
shelby upload file.txt blob.txt -e $(date -d "+30 days" +%s)

Upload Options

Directory Upload

shelby upload -r ./my-directory/ remote-dir/ -e "2025-12-31"
shelby upload --recursive ./website/ site/ --expiration tomorrow

Requirements:

• <dst> MUST end with / for recursive uploads
• Follows canonical directory layout

Example:

Local structure:

.
├── bar
└── foo
    ├── baz
    └── buzz

Uploaded as:

<account>/remote-dir/bar
<account>/remote-dir/foo/baz
<account>/remote-dir/foo/buzz

Note: No directory blobs created (no <account>/remote-dir/foo).

Auto-confirm for Scripts

# Skip interactive cost confirmation
shelby upload file.txt blob.txt -e tomorrow --assume-yes

Use case: Automation, CI/CD pipelines, scripts

Download Operations

Basic Download

shelby download <src> <dst>

Example:

shelby download videos/my-video.mp4 ./local-video.mp4
shelby download data/file.txt ./downloaded-file.txt

Download Options

Force Overwrite

shelby download blob.txt ./existing-file.txt --force

Directory Download

shelby download -r remote-dir/ ./local-dir/
shelby download --recursive site/ ./website/

Requirements:

• Both <src> and <dst> MUST end with /
• Recreates directory structure locally

Example:

Shelby blobs:

my-files/document.pdf
my-files/images/photo1.jpg
my-files/images/photo2.jpg

Download:

shelby download -r my-files/ ./local-files/

Result:

./local-files/
├── document.pdf
└── images/
    ├── photo1.jpg
    └── photo2.jpg

Validation Rules

Without --force:

• Parent directory of <dst> must exist
• <dst> file must not exist
• For recursive: <dst> directory must be empty

With --force:

• Any existing <dst> completely removed before download

Download from Other Accounts

Current limitation: CLI only downloads from active account.

Workaround - Use REST API:

curl https://api.shelbynet.shelby.xyz/shelby/v1/blobs/<account>/<blob-name>

Example:

# Download blob 'foo' from account 0x89ca7d...76357
curl https://api.shelbynet.shelby.xyz/shelby/v1/blobs/0x89ca7dfadf5788830b0d5826a56b370ced0d7938c4628f4b57f346ab54f76357/foo

Common Workflows

First-Time Setup

# 1. Install CLI
npm install -g @shelby-protocol/cli

# 2. Initialize
shelby init

# 3. List accounts
shelby account list

# 4. Fund account (get address from list command)
shelby faucet

# 5. Check balance
shelby account balance

# 6. Upload test file
shelby upload test.txt test-blob.txt -e tomorrow --assume-yes

# 7. Verify upload
shelby account blobs

# 8. Download file
shelby download test-blob.txt downloaded-test.txt

Upload Website

# Upload entire website directory
shelby upload -r ./dist/ my-site/ -e "2026-01-01" --assume-yes

# Verify uploaded files
shelby account blobs

# Download for verification
shelby download -r my-site/ ./verify-download/

Batch Upload with Script

#!/bin/bash

# Upload multiple files without prompts
for file in *.mp4; do
  shelby upload "$file" "videos/$file" \
    -e $(date -d "+90 days" +%s) \
    --assume-yes
done

Context Switching

# Work with local development network
shelby context use local
shelby upload test.txt dev-test.txt -e tomorrow

# Switch to production
shelby context use shelbynet
shelby upload prod.txt production-data.txt -e "2025-12-31"

Troubleshooting

Issue: "Insufficient ShelbyUSD tokens"

Error:

Insufficient Shelby tokens. Please fund your account with Shelby tokens to continue.

Solution:

# Check current balance
shelby account balance

# Get ShelbyUSD from faucet
shelby faucet
# Visit the faucet URL and fund your account

# Verify balance updated
shelby account balance

Issue: "Insufficient APT for gas"

Solution:

# Option 1: Use shelby faucet
shelby faucet

# Option 2: Use aptos CLI
aptos account fund-with-faucet --profile shelby-alice --amount 1000000000

Issue: "Blob already exists"

Error:

Blob name already exists

Solution:

• Choose different blob name, OR
• Delete old blob first, OR
• Wait for old blob to expire

Issue: "File changed size during upload"

Cause: File modified between listing and upload.

Solution:

• Ensure files are stable during upload
• Don't modify files during upload process
• Use --assume-yes and upload atomically

Issue: "Parent directory does not exist"

Error on download:

Parent directory of destination must exist

Solution:

# Create parent directory first
mkdir -p ./path/to/parent/

# Then download
shelby download blob.txt ./path/to/parent/file.txt

Issue: "Context not configured properly"

Solution:

# List contexts to see configuration
shelby context list

# Update context if needed
shelby context update shelbynet

# Or create new context
shelby context create mycontext

Issue: "Command not found: shelby"

Solution:

# Reinstall globally
npm install -g @shelby-protocol/cli

# Or ensure npm global bin is in PATH
npm config get prefix
export PATH="$(npm config get prefix)/bin:$PATH"

Best Practices

1. Use API Keys

# During init, provide API key to avoid rate limits
shelby init
# Enter API key when prompted

2. Auto-confirm for Scripts

# Always use --assume-yes in scripts/automation
shelby upload file.txt blob.txt -e tomorrow --assume-yes

3. Blob Naming Convention

# ✅ Use hierarchical paths
shelby upload file.txt users/alice/documents/file.txt

# ✅ Organize by type
shelby upload video.mp4 videos/2024/november/video.mp4

# ❌ Avoid trailing slashes (unless recursive)
shelby upload file.txt path/to/file/  # Invalid

4. Check Balance Before Large Uploads

# Check balance first
shelby account balance

# Then upload
shelby upload -r ./large-dir/ remote/ -e "2025-12-31"

5. Use Meaningful Expiration Times

# Temporary data
-e "in 7 days"

# Long-term storage
-e "2026-12-31"

# Time-based content
-e $(date -d "+90 days" +%s)

6. Verify Uploads

# After upload, always verify
shelby upload file.txt blob.txt -e tomorrow --assume-yes
shelby account blobs  # Confirm blob appears

# Optional: Download and compare
shelby download blob.txt verify.txt
diff file.txt verify.txt

Process for Helping Users

1. Identify Issue Category

Setup Issues:

• Installation problems
• Initialization failures
• Configuration errors

Funding Issues:

• Insufficient tokens
• Faucet not working
• Balance not updating

Upload/Download Issues:

• Command syntax errors
• File path problems
• Permission errors
• Blob naming issues

Configuration Issues:

• Account management
• Context switching
• Network selection

2. Search Documentation

# For upload/download issues
Read docs/tools_cli_commands_uploads-and-downloads.md

# For account issues
Read docs/tools_cli_commands_account-management.md

# For setup issues
Read docs/tools_cli.md

3. Provide Solution

Structure:

1. Diagnose - Identify root cause
2. Command - Show exact command to run
3. Verify - How to confirm it worked
4. Explain - Why the issue occurred
5. Prevent - Best practices to avoid in future

4. Follow-up

• Suggest related operations
• Mention best practices
• Recommend monitoring (balance checks, blob lists)

Response Style

• Command-first - Show exact CLI commands immediately
• Copy-paste ready - Format for easy terminal use
• Complete - Include all required flags and options
• Tested - Only suggest commands from official docs
• Contextual - Consider user's platform (bash vs zsh, etc.)

Example Interaction

User: "How do I upload a directory to Shelby?"

Response:
1. Show recursive upload command with all options
2. Explain directory naming requirements (trailing /)
3. Show canonical directory layout example
4. Mention --assume-yes for scripts
5. Suggest verification with `shelby account blobs`
6. Reference: docs/tools_cli_commands_uploads-and-downloads.md

References

When helping users, cite specific documentation:

• CLI guide: .claude/skills/blockchain/aptos/docs/tools_cli.md
• Commands: .claude/skills/blockchain/aptos/docs/tools_cli_commands_*.md
• Config file location: ~/.shelby/config.yaml

Limitations

• Only reference official Shelby CLI documentation
• Acknowledge current limitations (e.g., cross-account downloads)
• Suggest REST API workarounds when CLI has limitations
• Don't invent commands or flags not in documentation