@1sat/cli 0.0.20 → 0.0.22

package/package.json

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

package/src/args.ts

@@ -82,6 +82,24 @@ export function extractFlag(args: string[], flag: string): string | undefined {
 	return args[idx + 1]
 }
 
+/**
+ * Extract multiple values for a flag, supporting comma-delimited and multiple flag occurrences.
+ * Example: --tags a,b,c OR --tags a --tags b --tags c
+ */
+export function extractFlags(args: string[], flag: string): string[] {
+	const values: string[] = []
+	for (let i = 0; i < args.length - 1; i++) {
+		if (args[i] === flag) {
+			const value = args[i + 1]
+			if (value && !value.startsWith('--')) {
+				// Split comma-delimited values
+				values.push(...value.split(',').filter(v => v.length > 0))
+			}
+		}
+	}
+	return values
+}
+
 /**
  * Check if a boolean flag is present.
  */

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

@@ -8,6 +8,7 @@
  * 4. Config file creation
  */
 
+import { randomBytes } from 'node:crypto'
 import { PrivateKey } from '@bsv/sdk'
 import {
 	cancel,
@@ -162,18 +163,36 @@ export async function handleInitCommand(
 		// bitcoin-backup Touch ID not available — skip silently
 	}
 
-	// 4. Optional: storage identity key
-	const storageId = await text({
-		message: 'Storage identity key (for wallet persistence):',
-		defaultValue: '1sat-cli-default',
-		placeholder: '1sat-cli-default',
+	// 4. Generate random storage identity key
+	const storageId = `1sat-cli-${randomBytes(8).toString('hex')}`
+
+	// 5. Optional: remote storage configuration
+	const useRemote = await confirm({
+		message: 'Configure remote storage? (remote is active, local is backup)',
+		defaultValue: false,
 	})
-	if (isCancel(storageId)) {
-		cancel('Setup cancelled.')
-		process.exit(0)
+	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
 	}
 
-	// 5. Save everything
+	// 6. Save everything
 	ensureConfigDir()
 
 	await saveKey(wif, pw as string)
@@ -194,7 +213,8 @@ export async function handleInitCommand(
 	saveConfig({
 		...loadConfig(),
 		chain: chain as 'main' | 'test',
-		storageIdentityKey: storageId as string,
+		storageIdentityKey: storageId,
+		activeRemote,
 	})
 
 	const pk = PrivateKey.fromWif(wif)

package/src/commands/remote.ts

@@ -0,0 +1,336 @@
+/**
+ * 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,
+	})
+
+	// Load config early — needed for storage identity key lookups
+	const config = loadConfig()
+
+	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 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/commands/wallet.ts

@@ -1,11 +1,12 @@
 /**
  * Wallet commands - balance, address, send, send-all, info.
+ * BRC-100 interface commands - list-outputs, relinquish-output, list-actions, etc.
  */
 
 import { deriveDepositAddresses, sendAllBsv, sendBsv } from '@1sat/actions'
 import { confirm, isCancel } from '@clack/prompts'
 import type { GlobalFlags } from '../args'
-import { extractFlag } from '../args'
+import { extractFlag, extractFlags } from '../args'
 import { loadContext } from '../context'
 import { printCommandHelp } from '../help'
 import { loadKey, resolvePassword } from '../keys'
@@ -28,6 +29,22 @@ export async function handleWalletCommand(
 			return walletSendAll(rest, opts)
 		case 'info':
 			return walletInfo(rest, opts)
+		case 'list-outputs':
+			return walletListOutputs(rest, opts)
+		case 'relinquish-output':
+			return walletRelinquishOutput(rest, opts)
+		case 'list-actions':
+			return walletListActions(rest, opts)
+		case 'create-action':
+			return walletCreateAction(rest, opts)
+		case 'sign-action':
+			return walletSignAction(rest, opts)
+		case 'abort-action':
+			return walletAbortAction(rest, opts)
+		case 'list-certificates':
+			return walletListCertificates(rest, opts)
+		case 'relinquish-certificate':
+			return walletRelinquishCertificate(rest, opts)
 		default:
 			printCommandHelp('wallet', {
 				balance: 'Show wallet balance in satoshis',
@@ -35,6 +52,14 @@ export async function handleWalletCommand(
 				send: 'Send BSV to an address (--to <addr> --sats <amount>)',
 				'send-all': 'Send all BSV to an address (--to <addr>)',
 				info: 'Show wallet info (address, balance, network)',
+				'list-outputs': 'List wallet outputs (--basket <name> [--tags <t1,t2>] [--limit N])',
+				'relinquish-output': 'Remove output from basket (--basket <name> --output <txid.vout>)',
+				'list-actions': 'List wallet actions [--labels <l1,l2>] [--limit N]',
+				'create-action': 'Create action (JSON args)',
+				'sign-action': 'Sign action (JSON args)',
+				'abort-action': 'Abort action (--reference <ref>)',
+				'list-certificates': 'List certificates',
+				'relinquish-certificate': 'Relinquish certificate (--type <t> --serialNumber <s> --certifier <c>)',
 			})
 			if (subcommand && subcommand !== 'help') {
 				process.exit(1)
@@ -216,3 +241,258 @@ async function walletInfo(_args: string[], opts: GlobalFlags): Promise<void> {
 		await destroy()
 	}
 }
+
+// BRC-100 Interface Commands
+
+async function walletListOutputs(args: string[], opts: GlobalFlags): Promise<void> {
+	const basket = extractFlag(args, '--basket')
+	if (!basket) fatal('Missing required --basket <name>')
+
+	const tags = extractFlags(args, '--tags')
+	const limitStr = extractFlag(args, '--limit')
+	const limit = limitStr ? parseInt(limitStr, 10) : 10
+	if (!Number.isFinite(limit) || limit < 1 || limit > 10000) {
+		fatal('--limit must be between 1 and 10000')
+	}
+
+	const privateKey = await loadKey(resolvePassword())
+	const { ctx, destroy } = await loadContext(privateKey, {
+		chain: opts.chain,
+	})
+
+	try {
+		const listArgs: Parameters<typeof ctx.wallet.listOutputs>[0] = {
+			basket,
+			limit,
+		}
+		if (tags.length > 0) {
+			listArgs.tags = tags
+		}
+
+		const result = await ctx.wallet.listOutputs(listArgs)
+
+		if (opts.json) {
+			output(result, opts)
+		} else {
+			console.log(`\n${result.totalOutputs} total outputs in basket '${basket}':\n`)
+			for (const out of result.outputs) {
+				const tags = out.tags?.join(', ') || 'none'
+				console.log(`  ${out.outpoint} | ${out.satoshis} sats | tags: ${tags}`)
+			}
+			console.log()
+		}
+	} finally {
+		await destroy()
+	}
+}
+
+async function walletRelinquishOutput(
+	args: string[],
+	opts: GlobalFlags,
+): Promise<void> {
+	const basket = extractFlag(args, '--basket')
+	const outpoint = extractFlag(args, '--output')
+
+	if (!basket) fatal('Missing required --basket <name>')
+	if (!outpoint) fatal('Missing required --output <txid.vout>')
+
+	// Validate output format (txid.vout)
+	if (!outpoint.includes('.') || outpoint.split('.').length !== 2) {
+		fatal('Invalid --output format. Expected: txid.vout (e.g., abc123...0)')
+	}
+
+	const privateKey = await loadKey(resolvePassword())
+	const { ctx, destroy } = await loadContext(privateKey, {
+		chain: opts.chain,
+	})
+
+	try {
+		const result = await ctx.wallet.relinquishOutput({ basket, output: outpoint })
+
+		if (opts.json) {
+			output(result, opts)
+		} else {
+			output({ relinquished: true, basket, output: outpoint }, opts)
+		}
+	} finally {
+		await destroy()
+	}
+}
+
+async function walletListActions(args: string[], opts: GlobalFlags): Promise<void> {
+	const labels = extractFlags(args, '--labels')
+	const limitStr = extractFlag(args, '--limit')
+	const limit = limitStr ? parseInt(limitStr, 10) : 10
+	if (!Number.isFinite(limit) || limit < 1 || limit > 10000) {
+		fatal('--limit must be between 1 and 10000')
+	}
+
+	const privateKey = await loadKey(resolvePassword())
+	const { ctx, destroy } = await loadContext(privateKey, {
+		chain: opts.chain,
+	})
+
+	try {
+		const listArgs: Parameters<typeof ctx.wallet.listActions>[0] = {
+			labels: labels.length > 0 ? labels : ['*'], // Default to all labels if none specified
+			limit,
+		}
+
+		const result = await ctx.wallet.listActions(listArgs)
+
+		if (opts.json) {
+			output(result, opts)
+		} else {
+			console.log(`\n${result.totalActions} total actions:\n`)
+			for (const action of result.actions) {
+				console.log(`  ${action.txid || 'pending'} | status: ${action.status}`)
+			}
+			console.log()
+		}
+	} finally {
+		await destroy()
+	}
+}
+
+async function walletCreateAction(args: string[], opts: GlobalFlags): Promise<void> {
+	const jsonInput = args[0]
+
+	if (!jsonInput) fatal('Missing JSON arguments. Usage: wallet create-action \'{...}\'')
+
+	let actionArgs: Parameters<typeof ctx.wallet.createAction>[0]
+	try {
+		actionArgs = JSON.parse(jsonInput)
+	} catch {
+		fatal(`Invalid JSON: ${jsonInput}`)
+	}
+
+	const privateKey = await loadKey(resolvePassword())
+	const { ctx, destroy } = await loadContext(privateKey, {
+		chain: opts.chain,
+	})
+
+	try {
+		const result = await ctx.wallet.createAction(actionArgs)
+		output(result, opts)
+	} finally {
+		await destroy()
+	}
+}
+
+async function walletSignAction(args: string[], opts: GlobalFlags): Promise<void> {
+	const jsonInput = args[0]
+
+	if (!jsonInput) fatal('Missing JSON arguments. Usage: wallet sign-action \'{...}\'') 
+
+	let signArgs: Parameters<typeof ctx.wallet.signAction>[0]
+	try {
+		signArgs = JSON.parse(jsonInput)
+	} catch {
+		fatal(`Invalid JSON: ${jsonInput}`)
+	}
+
+	const privateKey = await loadKey(resolvePassword())
+	const { ctx, destroy } = await loadContext(privateKey, {
+		chain: opts.chain,
+	})
+
+	try {
+		const result = await ctx.wallet.signAction(signArgs)
+		output(result, opts)
+	} finally {
+		await destroy()
+	}
+}
+
+async function walletAbortAction(args: string[], opts: GlobalFlags): Promise<void> {
+	const reference = extractFlag(args, '--reference')
+
+	if (!reference) fatal('Missing required --reference <ref>')
+
+	const privateKey = await loadKey(resolvePassword())
+	const { ctx, destroy } = await loadContext(privateKey, {
+		chain: opts.chain,
+	})
+
+	try {
+		const result = await ctx.wallet.abortAction({ reference })
+		output(result, opts)
+	} finally {
+		await destroy()
+	}
+}
+
+async function walletListCertificates(
+	args: string[],
+	opts: GlobalFlags,
+): Promise<void> {
+	const certifiers = extractFlags(args, '--certifiers')
+	const types = extractFlags(args, '--types')
+	const limitStr = extractFlag(args, '--limit')
+	const limit = limitStr ? parseInt(limitStr, 10) : 10
+
+	if (!Number.isFinite(limit) || limit < 1 || limit > 10000) {
+		fatal('--limit must be between 1 and 10000')
+	}
+
+	const privateKey = await loadKey(resolvePassword())
+	const { ctx, destroy } = await loadContext(privateKey, {
+		chain: opts.chain,
+	})
+
+	try {
+		const listArgs: Parameters<typeof ctx.wallet.listCertificates>[0] = {
+			certifiers: certifiers.length > 0 ? certifiers : [],
+			types: types.length > 0 ? types : [],
+			limit,
+		}
+
+		const result = await ctx.wallet.listCertificates(listArgs)
+
+		if (opts.json) {
+			output(result, opts)
+		} else {
+			console.log(`\n${result.totalCertificates} total certificates:\n`)
+			for (const cert of result.certificates) {
+				console.log(`  ${cert.type} | ${cert.serialNumber} | ${cert.certifier}`)
+			}
+			console.log()
+		}
+	} finally {
+		await destroy()
+	}
+}
+
+async function walletRelinquishCertificate(
+	args: string[],
+	opts: GlobalFlags,
+): Promise<void> {
+	const type = extractFlag(args, '--type')
+	const serialNumber = extractFlag(args, '--serialNumber')
+	const certifier = extractFlag(args, '--certifier')
+
+	if (!type) fatal('Missing required --type <type>')
+	if (!serialNumber) fatal('Missing required --serialNumber <serial>')
+	if (!certifier) fatal('Missing required --certifier <certifier>')
+
+	const privateKey = await loadKey(resolvePassword())
+	const { ctx, destroy } = await loadContext(privateKey, {
+		chain: opts.chain,
+	})
+
+	try {
+		const result = await ctx.wallet.relinquishCertificate({
+			type,
+			serialNumber,
+			certifier,
+		})
+
+		if (opts.json) {
+			output(result, opts)
+		} else {
+			output({ relinquished: true, type, serialNumber, certifier }, opts)
+		}
+	} finally {
+		await destroy()
+	}
+}

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
@@ -46,6 +47,22 @@ ${bold('Wallet:')}
   ${cyan('wallet send-all')}          Send all BSV to an address
   ${cyan('wallet info')}              Show wallet info
 
+${bold('Wallet (BRC-100 Interface):')}
+  ${cyan('wallet list-outputs')}      List outputs in basket
+                               ${dim('--basket <name> [--tags <t1,t2>] [--limit N]')}
+  ${cyan('wallet relinquish-output')} Remove output from basket
+                               ${dim('--basket <name> --output <txid.vout>')}
+  ${cyan('wallet list-actions')}      List wallet actions
+                               ${dim('[--labels <l1,l2>] [--limit N]')}
+  ${cyan('wallet create-action')}     Create raw action (JSON args)
+  ${cyan('wallet sign-action')}       Sign raw action (JSON args)
+  ${cyan('wallet abort-action')}      Abort pending action
+                               ${dim('--reference <ref>')}
+  ${cyan('wallet list-certificates')} List certificates
+                               ${dim('[--certifiers <c1,c2>] [--types <t1,t2>] [--limit N]')}
+  ${cyan('wallet relinquish-certificate')} Relinquish certificate
+                               ${dim('--type <t> --serialNumber <s> --certifier <c>')}
+
 ${bold('Ordinals:')}
   ${cyan('ordinals list')}            List owned ordinals
   ${cyan('ordinals mint')}            Mint a new ordinal inscription
@@ -100,7 +117,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/
 `)
 }