@1sat/cli 0.0.20 → 0.0.21

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@1sat/cli",
-	"version": "0.0.20",
+	"version": "0.0.21",
 	"description": "CLI for 1Sat Ordinals SDK",
 	"type": "module",
 	"main": "./src/cli.ts",

package/src/cli.ts

@@ -8,13 +8,14 @@
 
 import { parseGlobalFlags } from './args'
 import { handleActionCommand } from './commands/action'
-import { handleMcpProxyCommand } from './commands/mcp-proxy'
 import { handleConfigCommand } from './commands/config'
 import { handleIdentityCommand } from './commands/identity'
 import { handleInitCommand } from './commands/init'
 import { handleLocksCommand } from './commands/locks'
+import { handleMcpProxyCommand } from './commands/mcp-proxy'
 import { handleOpnsCommand } from './commands/opns'
 import { handleOrdinalsCommand } from './commands/ordinals'
+import { handleRemoteCommand } from './commands/remote'
 import { handleSocialCommand } from './commands/social'
 import { handleSweepCommand } from './commands/sweep'
 import { handleTokensCommand } from './commands/tokens'
@@ -49,6 +50,10 @@ async function main(): Promise<void> {
 			await handleConfigCommand(rest, flags)
 			break
 
+		case 'remote':
+			await handleRemoteCommand(rest, flags)
+			break
+
 		case 'wallet':
 			await handleWalletCommand(rest, flags)
 			break

package/src/commands/config.ts

@@ -4,6 +4,7 @@
  * Subcommands:
  *   show   - Display current configuration
  *   set    - Set a configuration value
+ *   unset  - Remove a configuration key
  *   path   - Print config directory path
  */
 
@@ -28,8 +29,8 @@ import {
 const SETTABLE_KEYS: Array<keyof OneSatCliConfig> = [
 	'chain',
 	'dataDir',
-	'activeRemote',
 	'storageIdentityKey',
+	'monitorIntervalMinutes',
 ]
 
 export async function handleConfigCommand(
@@ -43,12 +44,15 @@ export async function handleConfigCommand(
 			return configShow(opts)
 		case 'set':
 			return configSet(rest, opts)
+		case 'unset':
+			return configUnset(rest, opts)
 		case 'path':
 			return configPath(opts)
 		default:
 			printCommandHelp('config', {
 				show: 'Display current configuration',
 				set: 'Set a config value (e.g. 1sat config set chain test)',
+				unset: 'Remove a configuration key (e.g. 1sat config unset chain)',
 				path: 'Print config directory path',
 			})
 			if (subcommand && subcommand !== 'help') {
@@ -69,8 +73,8 @@ function configShow(opts: GlobalFlags): void {
 	printKeyValue({
 		chain: config.chain,
 		dataDir: config.dataDir,
-		activeRemote: config.activeRemote ?? '(not set)',
 		storageIdentityKey: config.storageIdentityKey ?? '(not set)',
+		monitorIntervalMinutes: config.monitorIntervalMinutes,
 	})
 	console.log()
 	console.log(
@@ -98,11 +102,37 @@ function configSet(args: string[], opts: GlobalFlags): void {
 	if (key === 'chain' && value !== 'main' && value !== 'test') {
 		fatal("chain must be 'main' or 'test'")
 	}
+	if (key === 'monitorIntervalMinutes') {
+		const n = Number(value)
+		if (!Number.isFinite(n) || n < 0) {
+			fatal('monitorIntervalMinutes must be a non-negative number (0 to disable)')
+		}
+	}
 
 	const updated = updateConfig({ [key]: value })
 	output(opts.json ? updated : formatSuccess(`Set ${key} = ${value}`), opts)
 }
 
+function configUnset(args: string[], opts: GlobalFlags): void {
+	const [key] = args
+
+	if (!key) {
+		fatal(
+			`Usage: 1sat config unset <key>\n\nKeys that can be unset: ${SETTABLE_KEYS.join(', ')}`,
+		)
+	}
+
+	if (!SETTABLE_KEYS.includes(key as keyof OneSatCliConfig)) {
+		fatal(
+			`Unknown config key: ${key}\n\nKeys that can be unset: ${SETTABLE_KEYS.join(', ')}`,
+		)
+	}
+
+	// For other keys, use undefined
+	const updated = updateConfig({ [key]: undefined })
+	output(opts.json ? updated : formatSuccess(`Unset ${key}`), opts)
+}
+
 function configPath(opts: GlobalFlags): void {
 	const dir = getConfigDir()
 	output(opts.json ? { path: dir } : dir, opts)

package/src/commands/init.ts

@@ -173,7 +173,33 @@ export async function handleInitCommand(
 		process.exit(0)
 	}
 
-	// 5. Save everything
+	// 5. Optional: remote storage configuration
+	const useRemote = await confirm({
+		message: 'Configure remote storage? (remote is active, local is backup)',
+		defaultValue: false,
+	})
+	let activeRemote: string | undefined
+
+	if (useRemote) {
+		const url = await text({
+			message: 'Primary remote storage URL:',
+			validate(value) {
+				if (!value) return 'Required'
+				try {
+					new URL(value)
+				} catch {
+					return 'Invalid URL'
+				}
+			},
+		})
+		if (isCancel(url)) {
+			cancel('Setup cancelled.')
+			process.exit(0)
+		}
+		activeRemote = url as string
+	}
+
+	// 6. Save everything
 	ensureConfigDir()
 
 	await saveKey(wif, pw as string)
@@ -195,6 +221,7 @@ export async function handleInitCommand(
 		...loadConfig(),
 		chain: chain as 'main' | 'test',
 		storageIdentityKey: storageId as string,
+		activeRemote,
 	})
 
 	const pk = PrivateKey.fromWif(wif)

package/src/commands/remote.ts

@@ -0,0 +1,334 @@
+/**
+ * Remote storage management commands.
+ *
+ * Subcommands:
+ *   add        - Add a remote as backup (validates with immediate sync)
+ *   list       - Show all remotes and their status
+ *   delete     - Remove a remote from the backup list
+ *   set-active - Switch active storage to a remote or back to local
+ */
+
+import { confirm, isCancel, text } from '@clack/prompts'
+import type { GlobalFlags } from '../args'
+import { loadConfig, saveConfig } from '../config'
+import { loadContext } from '../context'
+import { printCommandHelp } from '../help'
+import { loadKey, resolvePassword } from '../keys'
+import { fatal, formatSuccess, formatWarning, output } from '../output'
+
+export async function handleRemoteCommand(
+	args: string[],
+	opts: GlobalFlags,
+): Promise<void> {
+	const [subcommand, ...rest] = args
+
+	switch (subcommand) {
+		case 'add':
+			return remoteAdd(rest, opts)
+		case 'list':
+			return remoteList(rest, opts)
+		case 'delete':
+			return remoteDelete(rest, opts)
+		case 'set-active':
+			return remoteSetActive(rest, opts)
+		default:
+			printCommandHelp('remote', {
+				add: 'Add a remote storage as backup (1sat remote add <url>)',
+				list: 'List all configured remotes and their status',
+				delete:
+					'Remove a remote from the backup list (1sat remote delete <url>)',
+				'set-active':
+					'Switch active storage (1sat remote set-active <url | local>)',
+			})
+			if (subcommand && subcommand !== 'help') {
+				process.exit(1)
+			}
+	}
+}
+
+// ============================================================================
+// remote add
+// ============================================================================
+
+async function remoteAdd(args: string[], opts: GlobalFlags): Promise<void> {
+	let url = args[0]
+
+	if (!url) {
+		url = (await text({
+			message: 'Remote storage URL:',
+			validate(value) {
+				if (!value) return 'Required'
+				try {
+					new URL(value)
+				} catch {
+					return 'Invalid URL'
+				}
+			},
+		})) as string
+		if (isCancel(url)) {
+			fatal('Cancelled')
+		}
+	} else {
+		try {
+			new URL(url)
+		} catch {
+			fatal(`Invalid URL: ${url}`)
+		}
+	}
+
+	const privateKey = await loadKey(resolvePassword())
+	const { walletResult, destroy } = await loadContext(privateKey, {
+		chain: opts.chain,
+	})
+
+	try {
+		// For backup-only, we use StorageClient via wallet-node
+		// biome-ignore lint/suspicious/noExplicitAny: StorageClient constructor not typed in wallet-toolbox
+		const { StorageClient } = await import('@1sat/wallet-node')
+		const wallet = walletResult.wallet as any
+		const client = new (StorageClient as any)(wallet, url)
+		await walletResult.storage.addWalletStorageProvider(client)
+
+		// When adding a backup, the remote may report itself as "active" which
+		// creates a conflicting active state. Re-assert local as active before syncing.
+		if (!walletResult.storage.isActiveEnabled) {
+			const localKey = config.storageIdentityKey ?? '1sat-cli-default'
+			await walletResult.storage.setActive(localKey)
+		}
+
+		await walletResult.storage.updateBackups()
+
+		// Persist to config — connectivity will be validated on next monitor run
+		const config = loadConfig()
+		const existing = config.backups ?? []
+		if (!existing.includes(url)) {
+			saveConfig({ ...config, backups: [...existing, url] })
+		}
+
+		if (opts.json) {
+			output({ url, status: 'added' }, opts)
+		} else {
+			console.log(formatSuccess(`  Added ${url} as backup`))
+			console.log(
+				formatWarning(
+					'  Note: Use "1sat remote set-active <url>" to make this remote the primary storage',
+				),
+			)
+		}
+	} finally {
+		await destroy()
+	}
+}
+
+// ============================================================================
+// remote list
+// ============================================================================
+
+async function remoteList(_args: string[], opts: GlobalFlags): Promise<void> {
+	const privateKey = await loadKey(resolvePassword())
+	const { walletResult, destroy } = await loadContext(privateKey, {
+		chain: opts.chain,
+	})
+
+	try {
+		const backups = walletResult.storage.getBackupStores?.() ?? []
+		const config = loadConfig()
+
+		// Use config for active determination — WalletStorageManager internal state
+		// can be misleading (a backup may appear as active after addWalletStorageProvider)
+		const isRemoteActive = Boolean(config.activeRemote)
+
+		if (opts.json) {
+			output(
+				{
+					activeStorage: isRemoteActive ? 'remote' : 'local',
+					backups: walletResult.storage.getAllStores?.() ?? [],
+					config: {
+						activeRemote: config.activeRemote ?? null,
+						backups: config.backups ?? [],
+					},
+				},
+				opts,
+			)
+			return
+		}
+
+		console.log()
+		console.log(`  ${bold('Active Storage:')} ${isRemoteActive ? 'remote' : 'local'}`)
+		if (isRemoteActive) {
+			console.log(
+				`  ${bold('Active Remote:')} ${config.activeRemote}`,
+			)
+		}
+		console.log()
+		if (backups.length === 0 && !config.backups?.length) {
+			console.log('  No remote storages configured')
+		} else {
+			console.log(`  ${bold('Backups:')}`)
+			const known = new Set(config.backups ?? [])
+			for (const b of backups) {
+				const isKnown = known.has(b)
+				console.log(`    ${isKnown ? '●' : '○'} ${b}`)
+			}
+			// Show configured but not yet connected
+			for (const url of config.backups ?? []) {
+				if (!backups.includes(url)) {
+					console.log(`    ? ${url} (not connected)`)
+				}
+			}
+		}
+		console.log()
+	} finally {
+		await destroy()
+	}
+}
+
+// ============================================================================
+// remote delete
+// ============================================================================
+
+async function remoteDelete(args: string[], opts: GlobalFlags): Promise<void> {
+	let url = args[0]
+
+	if (!url) {
+		url = (await text({
+			message: 'Remote storage URL to remove:',
+			validate(value) {
+				if (!value) return 'Required'
+			},
+		})) as string
+		if (isCancel(url)) {
+			fatal('Cancelled')
+		}
+	}
+
+	const config = loadConfig()
+	const backups = config.backups ?? []
+
+	if (!backups.includes(url)) {
+		fatal(`Remote not found in config: ${url}`)
+	}
+
+	// Confirm
+	const confirmed = await confirm({
+		message: `Remove ${url} from backups?`,
+		defaultValue: false,
+	})
+	if (isCancel(confirmed) || !confirmed) {
+		fatal('Cancelled')
+	}
+
+	saveConfig({ ...config, backups: backups.filter((u) => u !== url) })
+
+	if (opts.json) {
+		output({ url, status: 'removed' }, opts)
+	} else {
+		console.log(formatSuccess(`  Removed ${url} from backups`))
+	}
+}
+
+// ============================================================================
+// remote set-active
+// ============================================================================
+
+async function remoteSetActive(
+	args: string[],
+	opts: GlobalFlags,
+): Promise<void> {
+	let target = args[0]
+
+	if (!target) {
+		target = (await text({
+			message: 'Set active storage to (url or "local"):',
+			validate(value) {
+				if (!value) return 'Required'
+			},
+		})) as string
+		if (isCancel(target)) {
+			fatal('Cancelled')
+		}
+	}
+
+	const config = loadConfig()
+
+	if (target === 'local') {
+		// Switch back to local
+		if (!config.activeRemote && !config.backups?.length) {
+			fatal('No remote storages configured')
+		}
+
+		const privateKey = await loadKey(resolvePassword())
+		const { walletResult, destroy } = await loadContext(privateKey, {
+			chain: opts.chain,
+		})
+
+		try {
+			// Find the local storage's storageIdentityKey
+			const localKey = config.storageIdentityKey ?? '1sat-cli-default'
+
+			if (opts.json) {
+				output({ target: 'local', status: 'migrating' }, opts)
+			} else {
+				console.log('  Switching active storage to local...')
+			}
+
+			await walletResult.storage.setActive(localKey)
+
+			// Clear activeRemote from config
+			saveConfig({ ...config, activeRemote: undefined })
+
+			if (opts.json) {
+				output(
+					{ target: 'local', status: 'active', storageIdentityKey: localKey },
+					opts,
+				)
+			} else {
+				console.log(formatSuccess('  Local storage is now active'))
+			}
+		} finally {
+			await destroy()
+		}
+	} else {
+		// Switch to a remote
+		// Validate URL
+		try {
+			new URL(target)
+		} catch {
+			fatal(`Invalid URL: ${target}`)
+		}
+
+		const privateKey = await loadKey(resolvePassword())
+		const { walletResult, destroy } = await loadContext(privateKey, {
+			chain: opts.chain,
+		})
+
+		try {
+			if (opts.json) {
+				output({ target, status: 'migrating' }, opts)
+			} else {
+				console.log(`  Switching active storage to ${target}...`)
+			}
+
+			await walletResult.migrateRemote(target)
+
+			// Persist to config
+			saveConfig({ ...config, activeRemote: target })
+
+			if (opts.json) {
+				output({ target, status: 'active' }, opts)
+			} else {
+				console.log(formatSuccess(`  ${target} is now active`))
+			}
+		} finally {
+			await destroy()
+		}
+	}
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function bold(s: string): string {
+	return `\x1b[1m${s}\x1b[0m`
+}

package/src/config.ts

@@ -1,5 +1,5 @@
 /**
- * Config management for ~/.1sat/
+ * Config management for ~/.1sat/cli/
  *
  * Handles persistent configuration on disk with secure file permissions.
  */
@@ -8,7 +8,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 
-const CONFIG_DIR = join(homedir(), '.1sat')
+const CONFIG_DIR = join(homedir(), '.1sat', 'cli')
 const CONFIG_FILE = join(CONFIG_DIR, 'config.json')
 
 export interface OneSatCliConfig {
@@ -16,19 +16,48 @@ export interface OneSatCliConfig {
 	chain: 'main' | 'test'
 	/** Data directory for wallet databases */
 	dataDir: string
-	/** Remote storage URL for wallet sync */
+	/** Primary remote storage URL (active or backup) */
 	activeRemote?: string
+	/** Backup remote storage URLs */
+	backups?: string[]
 	/** Storage identity key for wallet persistence */
 	storageIdentityKey?: string
+	/** How often to run the monitor refresh (minutes). 0 disables auto-refresh. */
+	monitorIntervalMinutes: number
 }
 
 const DEFAULT_CONFIG: OneSatCliConfig = {
 	chain: 'main',
 	dataDir: join(CONFIG_DIR, 'data'),
+	monitorIntervalMinutes: 5,
+}
+
+// Monitor state — stored separately so we don't rewrite config.json on every command
+const MONITOR_STATE_FILE = join(CONFIG_DIR, 'monitor-state.json')
+
+export interface MonitorState {
+	lastMonitorRun: number // unix ms timestamp
+}
+
+export function loadMonitorState(): MonitorState {
+	if (!existsSync(MONITOR_STATE_FILE)) return { lastMonitorRun: 0 }
+	try {
+		const raw = readFileSync(MONITOR_STATE_FILE, 'utf8')
+		return JSON.parse(raw)
+	} catch {
+		return { lastMonitorRun: 0 }
+	}
+}
+
+export function saveMonitorState(state: MonitorState): void {
+	ensureConfigDir()
+	writeFileSync(MONITOR_STATE_FILE, JSON.stringify(state, null, 2), {
+		mode: 0o600,
+	})
 }
 
 /**
- * Ensure ~/.1sat/ exists with secure permissions.
+ * Ensure ~/.1sat/cli/ exists with secure permissions.
  */
 export function ensureConfigDir(): void {
 	if (!existsSync(CONFIG_DIR)) {

package/src/context.ts

@@ -7,7 +7,12 @@
 import { type OneSatContext, createContext } from '@1sat/actions'
 import { type NodeWalletResult, createNodeWallet } from '@1sat/wallet-node'
 import type { PrivateKey } from '@bsv/sdk'
-import { ensureDataDir, loadConfig } from './config'
+import {
+	ensureDataDir,
+	loadConfig,
+	loadMonitorState,
+	saveMonitorState,
+} from './config'
 
 /** Extended context that includes cleanup */
 export interface CliContext {
@@ -16,13 +21,35 @@ export interface CliContext {
 	destroy: () => Promise<void>
 }
 
+/**
+ * Run the monitor once if the interval has elapsed.
+ * This is called lazily by commands that need current state.
+ */
+async function runMonitorIfStale(
+	walletResult: NodeWalletResult,
+	intervalMinutes: number,
+): Promise<void> {
+	if (!walletResult.monitor) return // remote active, monitor runs remotely
+	if (intervalMinutes === 0) return // disabled by user
+
+	const state = loadMonitorState()
+	const now = Date.now()
+	const elapsed = now - state.lastMonitorRun
+	const intervalMs = intervalMinutes * 60 * 1000
+
+	if (elapsed >= intervalMs) {
+		await walletResult.monitor.runOnce()
+		saveMonitorState({ lastMonitorRun: Date.now() })
+	}
+}
+
 /**
  * Create a fully initialized OneSatContext for CLI use.
  *
  * Sets up:
  * - Node wallet with SQLite storage
  * - 1Sat services for API access
- * - Monitor for transaction lifecycle
+ * - Monitor for transaction lifecycle (lazy, interval-based)
  */
 export async function loadContext(
 	privateKey: PrivateKey,
@@ -37,17 +64,13 @@ export async function loadContext(
 		privateKey,
 		chain: opts.chain,
 		storageIdentityKey,
-		storage: {
-			client: 'better-sqlite3',
-			connection: {
-				filename: `${dataDir}/wallet-${opts.chain}.db`,
-			},
-			useNullAsDefault: true,
-		},
+		filename: `${dataDir}/wallet-${opts.chain}.db`,
 		activeRemote: config.activeRemote,
+		backups: config.backups,
 	})
 
-	walletResult.monitor?.startTasks()
+	// Run monitor once if interval has elapsed (lazy refresh)
+	await runMonitorIfStale(walletResult, config.monitorIntervalMinutes)
 
 	const ctx = createContext(walletResult.wallet, {
 		services: walletResult.services,

package/src/help.ts

@@ -38,6 +38,7 @@ ${bold('Usage:')}
 ${bold('Setup:')}
   ${cyan('init')}                     Interactive wallet setup wizard
   ${cyan('config')} <subcommand>      Manage configuration
+  ${cyan('remote')} <subcommand>      Manage remote storage
 
 ${bold('Wallet:')}
   ${cyan('wallet balance')}           Show wallet balance
@@ -100,7 +101,7 @@ ${bold('Environment Variables:')}
   ${dim('PRIVATE_KEY_WIF')}          Private key (bypasses encrypted keyfile)
   ${dim('ONESAT_PASSWORD')}          Password for encrypted keyfile
 
-${bold('Config:')} ~/.1sat/
+${bold('Config:')} ~/.1sat/cli/
 `)
 }