feat: add --network flag for mainnet and calibration network selection (#240)

* feat: add --network flag for mainnet and calibration network selection

Add support for selecting Filecoin network via --network flag or NETWORK
environment variable. Users can now easily switch between mainnet and
calibration testnet without manually specifying RPC URLs.

feat: add --network flag for mainnet and calibration network selection

* fix: format long option strings in CLI commands

Split long .option() calls across multiple lines to satisfy Biome formatter requirements in server.ts and cli-options.ts.

* fix: create re-usable network option with ENV and choice validation

* chore: fix lint

* fix: help output for network option

* fix: getRpcUrl returns url immediately if given

---------

Co-authored-by: Russell Dempsey <[email protected]>

Author: rjan90

README.md

@@ -6,7 +6,7 @@
 
 ## Status
 
-**⚠️ Not ready yet for production** - At least as of 2025-10-15, Filecoin Pin runs on Filecoin Calibration testnet only.  It's not ready for production use yet.
+**⚠️ Not ready yet for production** - Filecoin Pin supports both Filecoin Mainnet and Calibration testnet. The CLI defaults to Calibration testnet for safety, but you can use `--network mainnet` to connect to Mainnet, but filecoin-pin is not ready for production use yet.
 
 Register for updates and a later 2025 Q4 GA announcement at [filecoin.cloud](https://filecoin.cloud/).
 
@@ -125,9 +125,13 @@ If using a different affordance like the CLI or example GitHub Action, then the
 ### Prerequisites
 
 - **Node.js 24+** for CLI and library usage
-- **Filecoin Calibration testnet wallet** with:
-  - Test FIL for transaction gas ([Faucet](https://faucet.calibnet.chainsafe-fil.io/funds.html))
-  - Test USDFC stablecoin for storage payments ([USDFC Faucet](https://forest-explorer.chainsafe.dev/faucet/calibnet_usdfc))
+- **Filecoin wallet** (Calibration testnet or Mainnet) with:
+  - **For Calibration testnet:**
+    - Test FIL for transaction gas ([Faucet](https://faucet.calibnet.chainsafe-fil.io/funds.html))
+    - Test USDFC stablecoin for storage payments ([USDFC Faucet](https://forest-explorer.chainsafe.dev/faucet/calibnet_usdfc))
+  - **For Mainnet:**
+    - FIL for transaction gas
+    - USDFC stablecoin for storage payments
 
 ### Installation
 
@@ -143,11 +147,14 @@ npm install -g filecoin-pin
 # 1. Configure payment permissions (one-time setup)
 filecoin-pin payments setup --auto
 
-# 2. Upload a file to Filecoin
+# 2. Upload a file to Filecoin (defaults to Calibration testnet)
 filecoin-pin add myfile.txt
 
 # 3. Verify storage with cryptographic proofs
 filecoin-pin data-set <dataset-id>
+
+# To use Mainnet instead:
+filecoin-pin add myfile.txt --network mainnet
 ```
 
 For detailed guides, see:
@@ -159,13 +166,47 @@ Configuration of the Filecoin Pin CLI can be performed either with arguments, or
 
 The Pinning Server requires the use of environment variables, as detailed below.
 
+### Network Selection
+
+Filecoin Pin supports both **Mainnet** and **Calibration testnet**. By default, the CLI uses Calibration testnet during development.
+
+**Using the CLI:**
+```bash
+# Use Calibration testnet (default)
+filecoin-pin add myfile.txt
+
+# Use Mainnet
+filecoin-pin add myfile.txt --network mainnet
+
+# Explicitly specify Calibration
+filecoin-pin add myfile.txt --network calibration
+```
+
+**Using environment variables:**
+```bash
+# Set network via environment variable
+export NETWORK=mainnet
+filecoin-pin add myfile.txt
+
+# Or override RPC URL directly
+export RPC_URL=wss://wss.node.glif.io/apigw/lotus/rpc/v1
+filecoin-pin add myfile.txt
+```
+
+**Priority order:**
+1. `--rpc-url` flag (highest priority)
+2. `RPC_URL` environment variable
+3. `--network` flag or `NETWORK` environment variable
+4. Default to Calibration testnet
+
 ### Common CLI Arguments
 
 * `-h`, `--help`: Display help information for each command
 * `-V`, `--version`: Output the version number
 * `-v`, `--verbose`: Verbose output
 * `--private-key`: Ethereum-style (`0x`) private key, funded with USDFC (required)
-* `--rpc-url`: Filecoin RPC endpoint (default: Calibration testnet)
+* `--network`: Filecoin network to use: `mainnet` or `calibration` (default: `calibration`)
+* `--rpc-url`: Filecoin RPC endpoint (overrides `--network` if specified)
 
 Other arguments are possible for individual commands, use `--help` to find out more.
 
@@ -175,8 +216,11 @@ Other arguments are possible for individual commands, use `--help` to find out m
 # Required
 PRIVATE_KEY=0x...              # Ethereum private key with USDFC tokens
 
-# Optional
-RPC_URL=wss://...              # Filecoin RPC endpoint (default: Calibration testnet)
+# Optional - Network Configuration
+NETWORK=mainnet                # Network to use: mainnet or calibration (default: calibration)
+RPC_URL=wss://...              # Filecoin RPC endpoint (overrides NETWORK if specified)
+                                # Mainnet: wss://wss.node.glif.io/apigw/lotus/rpc/v1
+                                # Calibration: wss://wss.calibration.node.glif.io/apigw/lotus/rpc/v1
 
 # Optional for Pinning Server Daemon
 PORT=3456                      # Daemon server port

src/commands/server.ts

@@ -1,6 +1,7 @@
 import { RPC_URLS } from '@filoz/synapse-sdk'
 import { Command } from 'commander'
 import { startServer } from '../server.js'
+import { addNetworkOptions } from '../utils/cli-options.js'
 
 export const serverCommand = new Command('server')
   .description('Start the IPFS Pinning Service API server')
@@ -9,14 +10,23 @@ export const serverCommand = new Command('server')
   .option('--car-storage <path>', 'path for CAR file storage', './cars')
   .option('--database <path>', 'path to SQLite database', './pins.db')
   .option('--private-key <key>', 'private key for Synapse (or use PRIVATE_KEY env var)')
-  .option('--rpc-url <url>', 'RPC URL for Filecoin network', RPC_URLS.calibration.websocket)
+
+addNetworkOptions(serverCommand)
+  .option(
+    '--rpc-url <url>',
+    'RPC URL for Filecoin network (overrides --network, can also use RPC_URL env)',
+    RPC_URLS.calibration.websocket
+  )
   .action(async (options) => {
     // Override environment variables with CLI options if provided
     if (options.privateKey) {
       process.env.PRIVATE_KEY = options.privateKey
     }
+    // RPC URL takes precedence over network flag
     if (options.rpcUrl) {
       process.env.RPC_URL = options.rpcUrl
+    } else if (options.network) {
+      process.env.NETWORK = options.network
     }
     if (options.carStorage) {
       process.env.CAR_STORAGE_PATH = options.carStorage

src/common/get-rpc-url.ts

@@ -0,0 +1,39 @@
+import { RPC_URLS } from '@filoz/synapse-sdk'
+import type { CLIAuthOptions } from '../utils/cli-auth.js'
+
+/**
+ * Get the RPC URL from the CLI options and environment variables
+ *
+ * Network selection priority:
+ * 1. Explicit --rpc-url (highest priority)
+ * 2. RPC_URL environment variable
+ * 3. --network flag or NETWORK environment variable (converted to RPC URL)
+ * 4. Default to calibration
+ */
+export function getRpcUrl(options: CLIAuthOptions): string {
+  // Determine RPC URL with priority: explicit rpcUrl > RPC_URL env > network flag/env > default
+  let rpcUrl: string | undefined
+  if (options.rpcUrl || process.env.RPC_URL) {
+    // Explicit RPC URL takes highest priority
+    rpcUrl = options.rpcUrl || process.env.RPC_URL
+  }
+  if (rpcUrl) {
+    return rpcUrl
+  }
+  // Try to use network flag/env var
+  const network = (options.network || process.env.NETWORK)?.toLowerCase().trim()
+  if (network) {
+    // Validate network value
+    if (network !== 'mainnet' && network !== 'calibration') {
+      throw new Error(`Invalid network: "${network}". Must be "mainnet" or "calibration"`)
+    }
+    // Convert network to RPC URL
+    rpcUrl = RPC_URLS[network as 'mainnet' | 'calibration']?.websocket
+    if (!rpcUrl) {
+      throw new Error(`RPC URL not available for network: "${network}"`)
+    }
+    return rpcUrl
+  }
+
+  return RPC_URLS.calibration.websocket
+}

src/config.ts

@@ -1,6 +1,6 @@
 import { homedir, platform } from 'node:os'
 import { join } from 'node:path'
-import { RPC_URLS } from '@filoz/synapse-sdk'
+import { getRpcUrl } from './common/get-rpc-url.js'
 import type { Config } from './core/synapse/index.js'
 
 function getDataDirectory(): string {
@@ -31,20 +31,27 @@ function getDataDirectory(): string {
  *
  * This demonstrates configuration best practices for Synapse SDK:
  * - PRIVATE_KEY: Required for transaction signing (keep secure!)
- * - RPC_URL: Filecoin network endpoint (mainnet or calibration)
+ * - RPC_URL: Filecoin network endpoint (mainnet or calibration) - takes precedence over NETWORK
+ * - NETWORK: Filecoin network name (mainnet or calibration) - used if RPC_URL not set
  * - WARM_STORAGE_ADDRESS: Optional override for testing custom contracts
  */
 export function createConfig(): Config {
   const dataDir = getDataDirectory()
 
+  // Determine RPC URL: RPC_URL env var takes precedence, then NETWORK, then default to calibration
+  const rpcUrl = getRpcUrl({
+    network: process.env.NETWORK,
+    rpcUrl: process.env.RPC_URL,
+  })
+
   return {
     // Application-specific configuration
     port: parseInt(process.env.PORT ?? '3456', 10),
     host: process.env.HOST ?? 'localhost',
 
     // Synapse SDK configuration
     privateKey: process.env.PRIVATE_KEY, // Required: Ethereum-compatible private key
-    rpcUrl: process.env.RPC_URL ?? RPC_URLS.calibration.websocket, // Default: calibration testnet websocket
+    rpcUrl, // Determined from RPC_URL, NETWORK, or default to calibration
     warmStorageAddress: process.env.WARM_STORAGE_ADDRESS, // Optional: custom contract address
 
     // Storage paths

src/test/mocks/synapse-sdk.ts

@@ -82,6 +82,9 @@ export const RPC_URLS = {
   calibration: {
     websocket: 'wss://wss.calibration.node.glif.io/apigw/lotus/rpc/v1',
   },
+  mainnet: {
+    websocket: 'wss://wss.node.glif.io/apigw/lotus/rpc/v1',
+  },
 }
 
 // Export mock METADATA_KEYS matching SDK's structure

src/utils/cli-auth.ts

@@ -7,6 +7,7 @@
 
 import type { Synapse } from '@filoz/synapse-sdk'
 import { TELEMETRY_CLI_APP_NAME } from '../common/constants.js'
+import { getRpcUrl } from '../common/get-rpc-url.js'
 import type { SynapseSetupConfig } from '../core/synapse/index.js'
 import { initializeSynapse } from '../core/synapse/index.js'
 import { createLogger } from '../logger.js'
@@ -22,7 +23,9 @@ export interface CLIAuthOptions {
   walletAddress?: string | undefined
   /** Session key private key */
   sessionKey?: string | undefined
-  /** RPC endpoint URL */
+  /** Filecoin network: mainnet or calibration */
+  network?: string | undefined
+  /** RPC endpoint URL (overrides network if specified) */
   rpcUrl?: string | undefined
   /** Optional warm storage address override */
   warmStorageAddress?: string | undefined
@@ -48,9 +51,10 @@ export function parseCLIAuth(options: CLIAuthOptions): Partial<SynapseSetupConfi
   const privateKey = options.privateKey || process.env.PRIVATE_KEY
   const walletAddress = options.walletAddress || process.env.WALLET_ADDRESS
   const sessionKey = options.sessionKey || process.env.SESSION_KEY
-  const rpcUrl = options.rpcUrl || process.env.RPC_URL
   const warmStorageAddress = options.warmStorageAddress || process.env.WARM_STORAGE_ADDRESS
 
+  const rpcUrl = getRpcUrl(options)
+
   // Build config - only include defined values, validation happens in initializeSynapse()
   const config: any = {}
 

src/utils/cli-options.ts

@@ -6,7 +6,7 @@
  */
 
 import { RPC_URLS } from '@filoz/synapse-sdk'
-import type { Command } from 'commander'
+import { type Command, Option } from 'commander'
 
 /**
  * Decorator to add common authentication options to a Commander command
@@ -15,7 +15,8 @@ import type { Command } from 'commander'
  * - --private-key for standard authentication
  * - --wallet-address for session key authentication
  * - --session-key for session key authentication
- * - --rpc-url for network configuration
+ * - --network for network selection (mainnet or calibration)
+ * - --rpc-url for network configuration (overrides --network)
  *
  * The function modifies the command in-place and returns it for chaining.
  *
@@ -29,20 +30,26 @@ import type { Command } from 'commander'
  *   .description('Do something')
  *   .option('--my-option <value>', 'My custom option')
  *   .action(async (options) => {
- *     // options will include: privateKey, walletAddress, sessionKey, rpcUrl, myOption
- *     const { privateKey, walletAddress, sessionKey, rpcUrl, myOption } = options
+ *     // options will include: privateKey, walletAddress, sessionKey, network, rpcUrl, myOption
+ *     const { privateKey, walletAddress, sessionKey, network, rpcUrl, myOption } = options
  *   })
  *
  * // Add authentication options after the command is fully defined
  * addAuthOptions(myCommand)
  * ```
  */
 export function addAuthOptions(command: Command): Command {
-  return command
+  command
     .option('--private-key <key>', 'Private key for standard auth (can also use PRIVATE_KEY env)')
     .option('--wallet-address <address>', 'Wallet address for session key auth (can also use WALLET_ADDRESS env)')
     .option('--session-key <key>', 'Session key for session key auth (can also use SESSION_KEY env)')
-    .option('--rpc-url <url>', 'RPC endpoint (can also use RPC_URL env)', RPC_URLS.calibration.websocket)
+
+  return addNetworkOptions(command)
+    .option(
+      '--rpc-url <url>',
+      'RPC endpoint (can also use RPC_URL env, overrides --network)',
+      RPC_URLS.calibration.websocket
+    )
     .option(
       '--warm-storage-address <address>',
       'Warm storage contract address override (can also use WARM_STORAGE_ADDRESS env)'
@@ -80,3 +87,12 @@ export function addProviderOptions(command: Command): Command {
     )
     .option('--provider-id <id>', 'Override provider selection by ID (can also use PROVIDER_ID env)')
 }
+
+export function addNetworkOptions(command: Command): Command {
+  return command.addOption(
+    new Option('--network <network>', 'Filecoin network to use')
+      .choices(['mainnet', 'calibration'])
+      .env('NETWORK')
+      .default('calibration')
+  )
+}