@0xsota/storyx-cli

StoryX CLI

Fast IP lifecycle toolkit for Story Protocol — Create, manage, and license IP assets on Story Protocol blockchain with ease.

🚀 Features

• ✅ Complete IP Asset Management - Create, list, view, and link IP assets
• ✅ PIL License System - Built-in Programmable IP License templates
• ✅ Real-time Data - Fetch live data from Story Protocol API v4
• ✅ Multi-Network Support - Story Mainnet & Aeneid Testnet
• ✅ Secure Key Management - Encrypted private key storage
• ✅ Profile System - Manage multiple profiles and networks
• ✅ Project Scaffolding - Quick-start templates for developers
• ✅ User-Friendly Errors - Actionable error messages with guidance

---

📦 Installation

NPM (Recommended)

npm install -g @0xsota/storyx-cli

Verify Installation

storyx --version
# 0.1.0-beta.3.1

---

🎯 Quick Start

1. Initialize CLI

storyx init

This will:

• Create a new profile
• Configure network (Story Mainnet or Aeneid Testnet)
• Generate and encrypt a private key
• Set up your workspace

Example:

? Profile name: my-profile
? Network: Story Aeneid (Testnet)
? RPC URL: https://aeneid.storyrpc.io
? Explorer URL: https://aeneid.storyscan.io
? Enable telemetry: No
? Enter passphrase: ********
? Confirm passphrase: ********

✓ StoryX CLI initialized successfully!

Profile: my-profile
Network: story-aeneid
Address: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
Config: ~/.storyx/config.json

2. Get Testnet Tokens

Visit the Story Protocol faucet:

https://faucet.story.foundation

3. Create Your First IP Asset

storyx ip:create --title "My First IP" --tags "art,nft"

Output:

✓ IP Asset created successfully!

IP ID: 0x1234567890abcdef...
Transaction: 0xabcdef1234567890...
Explorer: https://aeneid.storyscan.io/tx/0xabcdef...

4. List Your IP Assets

storyx ip:list --limit 10

---

📚 Commands Reference

Configuration Commands

storyx init

Initialize StoryX CLI configuration (interactive setup).

storyx init

storyx profile

Manage profiles.

# List all profiles
storyx profile list

# Create new profile
storyx profile create <name>

# Switch profile
storyx profile switch <name>

# Delete profile
storyx profile delete <name>

storyx network

Manage network configurations.

# List networks
storyx network list

# Set network
storyx network set --rpc <url> --chain-id <id> --explorer <url>

storyx keys

Manage private keys.

# Create new key
storyx keys create

# Import existing key
storyx keys import --private-key <key>

# Export key
storyx keys export

---

IP Asset Commands

storyx ip:create

Create a new IP asset.

storyx ip:create --title <title> [options]

Options:

• --title <string> - IP asset title (required)
• --tags <string> - Comma-separated tags (e.g., "art,music,nft")
• --metadata-file <path> - Path to metadata JSON file
• --dry-run - Simulate without executing transaction

Example:

storyx ip:create --title "My Artwork" --tags "art,digital" --metadata-file ./metadata.json

storyx ip:list

List IP assets.

storyx ip:list [options]

Options:

• --owner <address> - Filter by owner address
• --limit <number> - Maximum results (default: 10)
• --json - Output as JSON

Example:

storyx ip:list --owner 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb --limit 5

storyx ip:show

Show IP asset details.

storyx ip:show <ip-id>

Example:

storyx ip:show 0x1234567890abcdef...

Output:

IP Asset Details
================
ID: 0x1234567890abcdef...
Title: My Artwork
Owner: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
Created: 2024-01-15T10:30:00Z
Metadata URI: ipfs://...

Parents: 0
Children: 2
  - 0xabcdef1234567890...
  - 0x9876543210fedcba...

storyx ip:link

Link IP assets (create derivative relationship).

storyx ip:link --parent <parent-id> --child <child-id> [options]

Options:

• --parent <string> - Parent IP asset ID (required)
• --child <string> - Child IP asset ID (required)
• --relation <string> - Relationship type: "derivative" or "remix" (default: "derivative")
• --dry-run - Simulate without executing

Example:

storyx ip:link --parent 0x1234... --child 0x5678... --relation derivative

storyx ip:tree

Display IP asset lineage tree.

storyx ip:tree --id <ip-id> [options]

Options:

• --id <string> - Root IP asset ID (required)
• --depth <number> - Tree depth (default: 10)
• --format <string> - Output format: "ascii" or "json" (default: "ascii")

Example:

storyx ip:tree --id 0x1234... --depth 3

Output:

0x1234567890abcdef... (My Original IP)
├── 0xabcdef1234567890... (Remix #1)
│   └── 0x9876543210fedcba... (Remix #1.1)
└── 0x5678901234abcdef... (Remix #2)

---

License Commands

storyx license:templates

List available PIL license templates.

storyx license:templates

Output:

Available License Templates
===========================
Name                              PIL Type                          Description
Non-Commercial Social Remixing    non-commercial-social-remixing    Free to remix and share, but no commercial use
Commercial Use                    commercial-use                    Commercial use allowed, no derivatives
Commercial Remix                  commercial-remix                  Commercial derivatives with revenue sharing

storyx license:create

Attach license to IP asset.

storyx license:create --ip <ip-id> --preset <preset> [options]

Options:

• --ip <string> - IP asset ID (required)
• --preset <string> - License preset: "non-commercial-social-remixing", "commercial-use", "commercial-remix", or "custom"
• --terms-file <path> - Custom license terms JSON file (for "custom" preset)
• --dry-run - Simulate without executing

Example:

# Use preset
storyx license:create --ip 0x1234... --preset non-commercial-social-remixing

# Custom terms
storyx license:create --ip 0x1234... --preset custom --terms-file ./terms.json

storyx license:apply

Mint license tokens.

storyx license:apply --ip <ip-id> --license <license-id> [options]

Options:

• --ip <string> - IP asset ID (required)
• --license <string> - License ID (required)
• --amount <number> - Number of tokens to mint (default: 1)
• --dry-run - Simulate without executing

Example:

storyx license:apply --ip 0x1234... --license 1 --amount 5

---

Scaffold Commands

storyx scaffold:project

Generate a new Story Protocol project.

storyx scaffold:project <project-name>

Example:

storyx scaffold:project my-story-app
cd my-story-app
npm install
npm run dev

Generated Structure:

my-story-app/
├── src/
│   └── index.ts          # Main entry point with examples
├── .env.example          # Environment variables template
├── package.json
├── tsconfig.json
└── README.md

---

🔧 Configuration

Config File Location

~/.storyx/config.json

Config Structure

{
  "defaultProfile": "my-profile",
  "telemetry": false,
  "profiles": [
    {
      "name": "my-profile",
      "network": "story-aeneid"
    }
  ],
  "networks": [
    {
      "name": "story-aeneid",
      "rpcUrl": "https://aeneid.storyrpc.io",
      "chainId": 1315,
      "explorerUrl": "https://aeneid.storyscan.io",
      "spgNftContract": "0xc32A8a0FF3beDDDa58393d022aF433e78739FAbc"
    }
  ]
}

Network Configurations

Story Mainnet:

• RPC: https://mainnet.storyrpc.io
• Chain ID: 1514
• Explorer: https://storyscan.io
• SPG NFT: 0x98971c660ac20880b60F86Cc3113eBd979eb3aAE

Story Aeneid Testnet:

• RPC: https://aeneid.storyrpc.io
• Chain ID: 1315
• Explorer: https://aeneid.storyscan.io
• SPG NFT: 0xc32A8a0FF3beDDDa58393d022aF433e78739FAbc

---

🎨 PIL License Templates

StoryX CLI includes three built-in PIL (Programmable IP License) templates:

1. Non-Commercial Social Remixing

Use case: Free sharing and remixing, no commercial use

Terms:

• ✅ Transferable
• ✅ Derivatives allowed
• ✅ Attribution required
• ✅ Reciprocal (derivatives must use same license)
• ❌ Commercial use prohibited

Example:

storyx license:create --ip 0x1234... --preset non-commercial-social-remixing

2. Commercial Use

Use case: Commercial use allowed, no derivatives

Terms:

• ✅ Transferable
• ✅ Commercial use allowed
• ✅ Attribution required
• ❌ Derivatives prohibited

Example:

storyx license:create --ip 0x1234... --preset commercial-use

3. Commercial Remix

Use case: Commercial derivatives with revenue sharing

Terms:

• ✅ Transferable
• ✅ Commercial use allowed
• ✅ Derivatives allowed
• ✅ Attribution required
• ✅ Revenue sharing (configurable)

Example:

storyx license:create --ip 0x1234... --preset commercial-remix

---

🛠️ Advanced Usage

Custom Metadata

Create a metadata JSON file:

{
  "name": "My Artwork",
  "description": "A beautiful digital artwork",
  "image": "ipfs://QmX...",
  "attributes": [
    {
      "trait_type": "Artist",
      "value": "Bernie"
    },
    {
      "trait_type": "Style",
      "value": "Abstract"
    }
  ]
}

Use with IP creation:

storyx ip:create --title "My Artwork" --metadata-file ./metadata.json

Custom License Terms

Create a terms JSON file:

{
  "transferable": true,
  "commercialUse": true,
  "derivativesAllowed": true,
  "derivativesAttribution": true,
  "commercialRevShare": 10,
  "uri": "https://example.com/license-terms.json"
}

Use with license creation:

storyx license:create --ip 0x1234... --preset custom --terms-file ./terms.json

Dry Run Mode

Test commands without executing transactions:

storyx ip:create --title "Test" --dry-run
storyx ip:link --parent 0x1234... --child 0x5678... --dry-run
storyx license:create --ip 0x1234... --preset commercial-use --dry-run

JSON Output

Get machine-readable output:

storyx ip:list --json > ips.json
storyx ip:tree --id 0x1234... --format json > tree.json

Verbose Mode

Enable detailed logging:

storyx -v ip:create --title "My IP"
storyx --verbose ip:list

---

🐛 Troubleshooting

Common Errors

"Insufficient funds"

Error: Insufficient funds. Get testnet tokens at: https://faucet.story.foundation

Solution: Visit the faucet and request testnet tokens for your address.

"Private key required for write operations"

Error: Private key required for write operations. Run: storyx keys import

Solution: Import or create a private key:

storyx keys import --private-key <your-key>
# or
storyx keys create

"IP Asset not found"

Error: IP Asset not found: 0x1234...

Solution: Verify the IP asset ID is correct and exists on the network.

"Network error"

Error: Network error. Check your connection and RPC endpoint configuration.

Solution: Check your internet connection and RPC URL:

storyx network list
storyx network set --rpc https://aeneid.storyrpc.io

---

📖 Examples

Complete Workflow

# 1. Initialize
storyx init

# 2. Create original IP
storyx ip:create --title "Original Artwork" --tags "art,original"
# Output: IP ID: 0xAAA...

# 3. Create derivative IP
storyx ip:create --title "Remix Artwork" --tags "art,remix"
# Output: IP ID: 0xBBB...

# 4. Link derivative to original
storyx ip:link --parent 0xAAA... --child 0xBBB... --relation derivative

# 5. Attach license to original
storyx license:create --ip 0xAAA... --preset commercial-remix

# 6. View IP tree
storyx ip:tree --id 0xAAA... --depth 3

# 7. List all your IPs
storyx ip:list --owner <your-address> --limit 20

Multi-Profile Setup

# Create testnet profile
storyx profile create testnet
storyx network set --rpc https://aeneid.storyrpc.io --chain-id 1315

# Create mainnet profile
storyx profile create mainnet
storyx network set --rpc https://mainnet.storyrpc.io --chain-id 1514

# Switch between profiles
storyx profile switch testnet
storyx ip:list

storyx profile switch mainnet
storyx ip:list

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

# Clone repository
git clone https://github.com/bernieio/storyx-cli.git
cd storyx-cli

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start

# Run tests
npm test

---

📄 License

MIT License - see LICENSE file for details.

---

👤 Author

Bernie (bernieio / 0xsota)

• Email: bernie.web3@gmail.com
• Telegram: @bernieio
• GitHub: @bernieio
• NPM: @0xsota/storyx-cli

---

🔗 Links

• NPM Package: https://www.npmjs.com/package/@0xsota/storyx-cli
• GitHub Repository: https://github.com/bernieio/storyx-cli
• Issues & Support: https://github.com/bernieio/storyx-cli/issues
• Story Protocol Docs: https://docs.story.foundation
• Story Protocol Faucet: https://faucet.story.foundation

---

⭐ Support

If you find this tool useful, please consider:

• ⭐ Starring the GitHub repository
• 🐛 Reporting bugs via GitHub Issues
• 💡 Suggesting features
• 📢 Sharing with the community

---

Built with ❤️ for the Story Protocol ecosystem