@1sat/cli 0.0.76 → 0.0.78

package/README.md

@@ -72,6 +72,12 @@ export PRIVATE_KEY_WIF="<your WIF key>"
 1sat wallet balance
 ```
 
+**Env file** (same keys as above; file values override the process environment for this run):
+
+```bash
+1sat --env-file mint.env wallet balance
+```
+
 **Encrypted keyfile (interactive use):**
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@1sat/cli",
-	"version": "0.0.76",
+	"version": "0.0.78",
 	"description": "CLI for 1Sat Ordinals SDK",
 	"type": "module",
 	"main": "./src/cli.ts",
@@ -26,12 +26,12 @@
 	],
 	"license": "MIT",
 	"dependencies": {
-		"@1sat/actions": "0.0.174",
+		"@1sat/actions": "0.0.184",
 		"@1sat/client": "0.0.42",
-		"@1sat/types": "0.0.33",
+		"@1sat/types": "0.0.34",
 		"@1sat/wallet-node": "0.0.57",
 		"@1sat/wallet-server": "0.0.26",
-		"@bsv/sdk": "^2.0.13",
+		"@bsv/sdk": "^2.1.6",
 		"@bsv/wallet-toolbox": "2.1.24",
 		"chalk": "^5.0.0",
 		"@clack/prompts": "^0.8.0",

package/src/args.ts

@@ -9,6 +9,8 @@ export interface GlobalFlags {
 	quiet: boolean
 	yes: boolean
 	chain: 'main' | 'test'
+	/** Paths from `--env-file` / `--env-file=path` (may be empty). */
+	envFiles: string[]
 	help: boolean
 	version: boolean
 	rest: string[]
@@ -24,6 +26,7 @@ export function parseGlobalFlags(args: string[]): GlobalFlags {
 	let chain: 'main' | 'test' = 'main'
 	let help = false
 	let version = false
+	const envFiles: string[] = []
 	const rest: string[] = []
 	const skip = new Set<number>()
 
@@ -56,6 +59,15 @@ export function parseGlobalFlags(args: string[]): GlobalFlags {
 				}
 				break
 			}
+			case '--env-file': {
+				const value = args[i + 1]
+				if (!value || value.startsWith('-')) {
+					throw new Error('--env-file requires a path')
+				}
+				envFiles.push(value)
+				skip.add(i + 1)
+				break
+			}
 			case '--help':
 			case '-h':
 				help = true
@@ -65,11 +77,19 @@ export function parseGlobalFlags(args: string[]): GlobalFlags {
 				version = true
 				break
 			default:
-				rest.push(arg)
+				if (arg.startsWith('--env-file=')) {
+					const value = arg.slice('--env-file='.length)
+					if (!value) {
+						throw new Error('--env-file requires a path')
+					}
+					envFiles.push(value)
+				} else {
+					rest.push(arg)
+				}
 		}
 	}
 
-	return { json, quiet, yes, chain, help, version, rest }
+	return { json, quiet, yes, chain, envFiles, help, version, rest }
 }
 
 /**

package/src/cli.ts

@@ -1,130 +1,10 @@
 #!/usr/bin/env bun
 
 /**
- * 1sat CLI - Command-line interface for 1Sat Ordinals SDK.
- *
- * Pure Bun CLI with manual arg parsing. No frameworks.
+ * CLI entry. Must set DOTENV_CONFIG_QUIET before any import that pulls in
+ * @bsv/wallet-toolbox (Setup / MonitorDaemon call dotenv.config() at load).
  */
 
-import { parseGlobalFlags } from './args'
-import { handleActionCommand } from './commands/action'
-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 { handleServeCommand } from './commands/serve'
-import { handleSocialCommand } from './commands/social'
-import { handleSweepCommand } from './commands/sweep'
-import { handleTokensCommand } from './commands/tokens'
-import { handleTxCommand } from './commands/tx'
-import { handleWalletCommand } from './commands/wallet'
-import { getCommand, printCommandHelp, printHelp, printVersion } from './help'
-import { formatError } from './output'
+process.env.DOTENV_CONFIG_QUIET = 'true'
 
-const rawArgs = process.argv.slice(2)
-
-async function main(): Promise<void> {
-	const flags = parseGlobalFlags(rawArgs)
-
-	if (flags.version) {
-		printVersion()
-		process.exit(0)
-	}
-
-	const [command, ...rest] = flags.rest
-
-	if (!command) {
-		printHelp(flags.json)
-		process.exit(0)
-	}
-
-	if (flags.help) {
-		if (getCommand(command)) {
-			printCommandHelp(command, flags.json)
-		} else {
-			printHelp(flags.json)
-		}
-		process.exit(0)
-	}
-
-	switch (command) {
-		case 'init':
-			await handleInitCommand(rest, flags)
-			break
-
-		case 'config':
-			await handleConfigCommand(rest, flags)
-			break
-
-		case 'remote':
-			await handleRemoteCommand(rest, flags)
-			break
-
-		case 'wallet':
-			await handleWalletCommand(rest, flags)
-			break
-
-		case 'ordinals':
-			await handleOrdinalsCommand(rest, flags)
-			break
-
-		case 'tokens':
-			await handleTokensCommand(rest, flags)
-			break
-
-		case 'locks':
-			await handleLocksCommand(rest, flags)
-			break
-
-		case 'identity':
-			await handleIdentityCommand(rest, flags)
-			break
-
-		case 'social':
-			await handleSocialCommand(rest, flags)
-			break
-
-		case 'opns':
-			await handleOpnsCommand(rest, flags)
-			break
-
-		case 'sweep':
-			await handleSweepCommand(rest, flags)
-			break
-
-		case 'action':
-			await handleActionCommand(rest, flags)
-			break
-
-		case 'tx':
-			await handleTxCommand(rest, flags)
-			break
-
-		case 'mcp-proxy':
-			await handleMcpProxyCommand()
-			break
-
-		case 'serve':
-			await handleServeCommand(rest, flags)
-			break
-
-		case 'help':
-			printHelp(flags.json)
-			break
-
-		default:
-			console.error(formatError(`Unknown command: ${command}`))
-			printHelp(flags.json)
-			process.exit(1)
-	}
-}
-
-main().catch((err) => {
-	console.error(formatError(`Error: ${err.message}`))
-	if (process.env.DEBUG) console.error(err.stack)
-	process.exit(1)
-})
+await import('./main.ts')

package/src/commands/serve.ts

@@ -325,7 +325,7 @@ async function runWithStorage(
 		async stop() {
 			if (mode !== 'wallet') {
 				walletResult.monitor.stopTasks()
-				clearMonitorPid(resolved.dataDir)
+				clearMonitorPid(resolved.dataDir, process.pid)
 			}
 			if (serverHandle) await serverHandle.stop()
 			// Accounts shares the wallet's connection — walletResult.destroy

package/src/context.ts

@@ -1,14 +1,17 @@
 /**
  * OneSatContext factory for CLI commands.
  *
- * Creates a fully initialized wallet context with services and monitor.
+ * Creates a fully initialized wallet context with services. Monitor work is
+ * not run in-process (avoids toolbox/console noise on the TTY). After the
+ * wallet is destroyed, a detached `__monitor-once` child may run against the
+ * same storage with logs in <dataDir>/monitor.log.
  */
 
 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 { readLiveMonitorPid } from './monitor-lock'
+import { spawnDetachedMonitorOnce } from './monitor-once'
 
 /** Extended context that includes cleanup */
 export interface CliContext {
@@ -23,10 +26,8 @@ export interface CliContext {
  * Sets up:
  * - Node wallet with SQLite storage
  * - 1Sat services for API access
- * - Monitor for transaction lifecycle. When local storage is the active
- *   store, the wallet factory fires `monitor.runOnce()` internally on
- *   creation; individual tasks self-throttle via their own intervals, so
- *   repeated CLI invocations are cheap.
+ * - No in-process monitor.runOnce(); a background once-run is scheduled on
+ *   destroy when local storage is active and no other monitor owner is live.
  */
 export async function loadContext(
 	privateKey: PrivateKey,
@@ -37,8 +38,6 @@ export async function loadContext(
 
 	const storageIdentityKey = config.storageIdentityKey ?? '1sat-cli-default'
 
-	const skipInitialMonitor = readLiveMonitorPid(dataDir) !== undefined
-
 	const walletResult = await createNodeWallet({
 		privateKey,
 		chain: opts.chain,
@@ -49,7 +48,8 @@ export async function loadContext(
 		},
 		activeRemote: config.activeRemote,
 		backups: config.backups,
-		skipInitialMonitor,
+		// Monitor runs in a detached child after destroy, or in `1sat serve`.
+		skipInitialMonitor: true,
 	})
 
 	const ctx = createContext(walletResult.wallet, {
@@ -61,6 +61,14 @@ export async function loadContext(
 	return {
 		ctx,
 		walletResult,
-		destroy: walletResult.destroy,
+		destroy: async () => {
+			await walletResult.destroy()
+			spawnDetachedMonitorOnce({
+				dataDir,
+				chain: opts.chain,
+				privateKeyWif: privateKey.toWif(),
+				activeRemote: config.activeRemote,
+			})
+		},
 	}
 }

package/src/help.ts

@@ -62,6 +62,12 @@ export const GLOBAL_OPTIONS: ArgSpec[] = [
 		values: '<main|test>',
 		description: 'Network (default: main)',
 	},
+	{
+		flag: '--env-file',
+		values: '<path>',
+		description:
+			'Load env vars from a file (repeatable; file values override existing env)',
+	},
 	{ flag: '--help', description: 'Show help (also -h)' },
 	{ flag: '--version', description: 'Show version (also -v)' },
 ]

package/src/main.ts

@@ -0,0 +1,158 @@
+/**
+ * 1sat CLI - Command-line interface for 1Sat Ordinals SDK.
+ *
+ * Pure Bun CLI with manual arg parsing. No frameworks.
+ *
+ * Loaded after entry bootstrap sets DOTENV_CONFIG_QUIET so wallet-toolbox
+ * import-time dotenv.config() calls stay silent.
+ */
+
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { config as loadEnv } from 'dotenv'
+import { parseGlobalFlags } from './args'
+import { handleActionCommand } from './commands/action'
+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 { handleServeCommand } from './commands/serve'
+import { handleSocialCommand } from './commands/social'
+import { handleSweepCommand } from './commands/sweep'
+import { handleTokensCommand } from './commands/tokens'
+import { handleTxCommand } from './commands/tx'
+import { handleWalletCommand } from './commands/wallet'
+import { getCommand, printCommandHelp, printHelp, printVersion } from './help'
+import { runMonitorOnce } from './monitor-once'
+import { formatError } from './output'
+
+const rawArgs = process.argv.slice(2)
+
+/** Load `--env-file` paths into process.env. File values win over existing env. */
+function applyEnvFiles(paths: string[]): void {
+	for (const p of paths) {
+		const abs = resolve(p)
+		if (!existsSync(abs)) {
+			throw new Error(`Env file not found: ${p}`)
+		}
+		const result = loadEnv({ path: abs, quiet: true, override: true })
+		if (result.error) {
+			throw result.error
+		}
+	}
+}
+
+async function main(): Promise<void> {
+	const flags = parseGlobalFlags(rawArgs)
+	if (flags.envFiles.length > 0) {
+		applyEnvFiles(flags.envFiles)
+	}
+
+	if (flags.version) {
+		printVersion()
+		process.exit(0)
+	}
+
+	const [command, ...rest] = flags.rest
+
+	if (!command) {
+		printHelp(flags.json)
+		process.exit(0)
+	}
+
+	if (flags.help) {
+		if (getCommand(command)) {
+			printCommandHelp(command, flags.json)
+		} else {
+			printHelp(flags.json)
+		}
+		process.exit(0)
+	}
+
+	switch (command) {
+		case 'init':
+			await handleInitCommand(rest, flags)
+			break
+
+		case 'config':
+			await handleConfigCommand(rest, flags)
+			break
+
+		case 'remote':
+			await handleRemoteCommand(rest, flags)
+			break
+
+		case 'wallet':
+			await handleWalletCommand(rest, flags)
+			break
+
+		case 'ordinals':
+			await handleOrdinalsCommand(rest, flags)
+			break
+
+		case 'tokens':
+			await handleTokensCommand(rest, flags)
+			break
+
+		case 'locks':
+			await handleLocksCommand(rest, flags)
+			break
+
+		case 'identity':
+			await handleIdentityCommand(rest, flags)
+			break
+
+		case 'social':
+			await handleSocialCommand(rest, flags)
+			break
+
+		case 'opns':
+			await handleOpnsCommand(rest, flags)
+			break
+
+		case 'sweep':
+			await handleSweepCommand(rest, flags)
+			break
+
+		case 'action':
+			await handleActionCommand(rest, flags)
+			break
+
+		case 'tx':
+			await handleTxCommand(rest, flags)
+			break
+
+		case 'mcp-proxy':
+			await handleMcpProxyCommand()
+			break
+
+		case 'serve':
+			await handleServeCommand(rest, flags)
+			break
+
+		// Hidden: parent CLI spawns this after wallet destroy so monitor
+		// stdout/stderr go to ~/.1sat/cli/monitor.log instead of the TTY.
+		case '__monitor-once':
+			await runMonitorOnce(flags.chain)
+			break
+
+		case 'help':
+			printHelp(flags.json)
+			break
+
+		default:
+			console.error(formatError(`Unknown command: ${command}`))
+			printHelp(flags.json)
+			process.exit(1)
+	}
+}
+
+main().catch((err) => {
+	console.error(formatError(`Error: ${err.message}`))
+	if (process.env.DEBUG) console.error(err.stack)
+	process.exit(1)
+})

package/src/monitor-lock.ts

@@ -3,10 +3,9 @@
  * and a long-running `1sat serve` process.
  *
  * - `1sat serve` (modes that run the monitor) writes the pid on startup and
- *   removes it on clean shutdown.
- * - CLI invocations read the file and, if the pid is alive, skip firing
- *   their own `monitor.runOnce()` to avoid duplicate work against the same
- *   SQLite file.
+ *   removes it on clean shutdown (only if still the owner).
+ * - Detached `__monitor-once` children claim the same lock while they run.
+ * - CLI parents skip spawning another once-run when a live owner is present.
  */
 
 import { readFileSync, unlinkSync, writeFileSync } from 'node:fs'
@@ -25,9 +24,23 @@ export function writeMonitorPid(
 	writeFileSync(monitorPidPath(dataDir), `${pid}\n`, 'utf8')
 }
 
-export function clearMonitorPid(dataDir: string): void {
+/**
+ * Remove the pid file. When `onlyPid` is set, only unlink if the file still
+ * contains that pid (avoids a short once-run clearing a serve owner that
+ * started while the once-run was shutting down).
+ */
+export function clearMonitorPid(
+	dataDir: string,
+	onlyPid?: number,
+): void {
+	const path = monitorPidPath(dataDir)
 	try {
-		unlinkSync(monitorPidPath(dataDir))
+		if (onlyPid !== undefined) {
+			const raw = readFileSync(path, 'utf8')
+			const pid = Number.parseInt(raw.trim(), 10)
+			if (pid !== onlyPid) return
+		}
+		unlinkSync(path)
 	} catch {}
 }
 

package/src/monitor-once.ts

@@ -0,0 +1,135 @@
+/**
+ * Detached one-shot monitor run for CLI commands.
+ *
+ * Parent commands skip in-process monitor.runOnce() so toolbox/console noise
+ * never hits the TTY. After the wallet is closed they spawn this process;
+ * its stdout/stderr append to <dataDir>/monitor.log.
+ */
+
+import { type SpawnOptions, spawn } from 'node:child_process'
+import { appendFileSync, closeSync, openSync } from 'node:fs'
+import { join } from 'node:path'
+import { createNodeWallet } from '@1sat/wallet-node'
+import { ensureDataDir, loadConfig } from './config'
+import { loadKey } from './keys'
+import {
+	clearMonitorPid,
+	readLiveMonitorPid,
+	writeMonitorPid,
+} from './monitor-lock'
+
+export const MONITOR_LOG_FILENAME = 'monitor.log'
+
+export function monitorLogPath(dataDir: string): string {
+	return join(dataDir, MONITOR_LOG_FILENAME)
+}
+
+/**
+ * Spawn a detached `__monitor-once` child. No-op when a live monitor owner
+ * exists (serve or another once-run) or when a remote is the active store.
+ * Spawn failures are reported on the parent stderr; child logs go to file.
+ */
+export function spawnDetachedMonitorOnce(opts: {
+	dataDir: string
+	chain: 'main' | 'test'
+	privateKeyWif: string
+	activeRemote?: string
+}): void {
+	if (opts.activeRemote) return
+	if (readLiveMonitorPid(opts.dataDir) !== undefined) return
+
+	const logPath = monitorLogPath(opts.dataDir)
+	try {
+		appendFileSync(
+			logPath,
+			`\n--- monitor-once ${new Date().toISOString()} ---\n`,
+		)
+	} catch {
+		// still try to spawn; openSync may surface the real error
+	}
+
+	let logFd: number
+	try {
+		logFd = openSync(logPath, 'a')
+	} catch (err) {
+		console.error(
+			`[monitor] failed to open log ${logPath}: ${(err as Error).message}`,
+		)
+		return
+	}
+
+	const args = ['__monitor-once', '--chain', opts.chain]
+	const env: NodeJS.ProcessEnv = {
+		...process.env,
+		DOTENV_CONFIG_QUIET: 'true',
+		PRIVATE_KEY_WIF: opts.privateKeyWif,
+	}
+
+	try {
+		const child = spawnSelf(args, {
+			detached: true,
+			stdio: ['ignore', logFd, logFd],
+			env,
+		})
+		child.unref()
+	} catch (err) {
+		console.error(
+			`[monitor] failed to start background run: ${(err as Error).message}`,
+		)
+	} finally {
+		closeSync(logFd)
+	}
+}
+
+function spawnSelf(args: string[], options: SpawnOptions) {
+	const script = process.argv[1]
+	if (
+		script &&
+		(script.endsWith('.ts') ||
+			script.endsWith('.tsx') ||
+			script.endsWith('.js') ||
+			script.endsWith('.mjs') ||
+			script.endsWith('.cjs'))
+	) {
+		return spawn(process.execPath, [script, ...args], options)
+	}
+	return spawn(process.execPath, args, options)
+}
+
+/**
+ * Child entry: open the wallet, run monitor once, exit. Claims monitor.pid
+ * while running so concurrent CLI spawns skip; clears only if we still own it.
+ */
+export async function runMonitorOnce(chain: 'main' | 'test'): Promise<void> {
+	const config = loadConfig()
+	if (config.activeRemote) return
+
+	const dataDir = ensureDataDir()
+	const existing = readLiveMonitorPid(dataDir)
+	if (existing !== undefined && existing !== process.pid) return
+
+	const privateKey = await loadKey()
+	writeMonitorPid(dataDir)
+	try {
+		const storageIdentityKey = config.storageIdentityKey ?? '1sat-cli-default'
+		const walletResult = await createNodeWallet({
+			privateKey,
+			chain,
+			storageIdentityKey,
+			storage: {
+				provider: 'bun-sqlite',
+				filename: `${dataDir}/wallet-${chain}.db`,
+			},
+			activeRemote: config.activeRemote,
+			backups: config.backups,
+			skipInitialMonitor: true,
+		})
+		try {
+			await walletResult.monitor.runOnce()
+		} finally {
+			await walletResult.destroy()
+		}
+	} finally {
+		clearMonitorPid(dataDir, process.pid)
+	}
+}