@durable-streams/cli 0.1.6 → 0.1.8

package/README.md

@@ -69,6 +69,11 @@ durable-stream-dev read my-stream
 ### Environment Variables
 
 - `STREAM_URL` - Base URL of the stream server (default: `http://localhost:4437`)
+- `STREAM_AUTH` - Authorization header value (e.g., `Bearer my-token`)
+
+### Global Options
+
+- `--auth <value>` - Authorization header value (overrides `STREAM_AUTH` env var)
 
 ### Write Options
 
@@ -125,6 +130,23 @@ durable-stream-dev read <stream_id>
 durable-stream-dev delete <stream_id>
 ```
 
+### Authentication
+
+Use the `--auth` flag or `STREAM_AUTH` environment variable to authenticate:
+
+```bash
+# Using environment variable
+export STREAM_AUTH="Bearer my-token"
+durable-stream-dev read my-stream
+
+# Using --auth flag (overrides env var)
+durable-stream-dev --auth "Bearer my-token" read my-stream
+
+# Works with any auth scheme
+durable-stream-dev --auth "Basic dXNlcjpwYXNz" read my-stream
+durable-stream-dev --auth "ApiKey abc123" read my-stream
+```
+
 ## Complete Example Workflow
 
 ```bash

package/dist/index.cjs

@@ -23,6 +23,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
+const node_http = __toESM(require("node:http"));
 const node_path = __toESM(require("node:path"));
 const node_process = __toESM(require("node:process"));
 const node_url = __toESM(require("node:url"));
@@ -89,11 +90,146 @@ function parseWriteArgs(args) {
 	};
 }
 
+//#endregion
+//#region src/validation.ts
+/**
+* Validate a URL string.
+* Must be a valid HTTP or HTTPS URL.
+*/
+function validateUrl(url) {
+	if (!url || !url.trim()) return {
+		valid: false,
+		error: `URL cannot be empty`
+	};
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return {
+			valid: false,
+			error: `Invalid URL format: "${url}"\n  Expected format: http://host:port or https://host:port`
+		};
+	}
+	if (parsed.protocol !== `http:` && parsed.protocol !== `https:`) return {
+		valid: false,
+		error: `Invalid URL protocol: "${parsed.protocol}"\n  Only http:// and https:// are supported`
+	};
+	if (!parsed.hostname) return {
+		valid: false,
+		error: `URL must include a hostname: "${url}"`
+	};
+	return { valid: true };
+}
+/**
+* Normalize a base URL by removing trailing slashes.
+* This prevents double-slashes when appending paths (e.g., "http://host/" + "/v1/...").
+*/
+function normalizeBaseUrl(url) {
+	return url.replace(/\/+$/, ``);
+}
+/**
+* Validate an authorization header value.
+* Returns valid=true for any non-empty value, but includes a warning
+* if the value doesn't match common auth schemes (Bearer, Basic, ApiKey, Token).
+*/
+function validateAuth(auth) {
+	if (!auth || !auth.trim()) return {
+		valid: false,
+		error: `Authorization value cannot be empty`
+	};
+	const trimmed = auth.trim();
+	const lowerTrimmed = trimmed.toLowerCase();
+	const hasScheme = [
+		`bearer `,
+		`basic `,
+		`apikey `,
+		`token `
+	].some((scheme) => lowerTrimmed.startsWith(scheme));
+	if (!hasScheme && !trimmed.includes(` `)) return {
+		valid: true,
+		warning: `Warning: Authorization value doesn't match common formats.\n  Expected: "Bearer <token>", "Basic <credentials>", or "ApiKey <key>"`
+	};
+	return { valid: true };
+}
+/**
+* Validate a stream ID.
+* Must be 1-256 characters containing only: letters, numbers, underscores,
+* hyphens, dots, and colons (URL-safe characters).
+*/
+function validateStreamId(streamId) {
+	if (!streamId || !streamId.trim()) return {
+		valid: false,
+		error: `Stream ID cannot be empty`
+	};
+	const validPattern = /^[a-zA-Z0-9_\-.:]+$/;
+	if (!validPattern.test(streamId)) return {
+		valid: false,
+		error: `Invalid stream ID: "${streamId}"\n  Stream IDs can only contain letters, numbers, underscores, hyphens, dots, and colons`
+	};
+	if (streamId.length > 256) return {
+		valid: false,
+		error: `Stream ID too long (${streamId.length} chars)\n  Maximum length is 256 characters`
+	};
+	return { valid: true };
+}
+
 //#endregion
 //#region src/index.ts
 const STREAM_URL = process.env.STREAM_URL || `http://localhost:4437`;
-function printUsage() {
-	console.error(`
+const STREAM_AUTH = process.env.STREAM_AUTH;
+/**
+* Parse global options (--url, --auth) from args.
+* Falls back to STREAM_URL/STREAM_AUTH env vars when flags not provided.
+* Returns the parsed options, remaining args, and any warnings.
+*/
+function parseGlobalOptions(args) {
+	const options = {};
+	const remainingArgs = [];
+	const warnings = [];
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === `--url`) {
+			const value = args[i + 1];
+			if (!value || value.startsWith(`--`)) throw new Error(`--url requires a value\n  Example: --url "http://localhost:4437"`);
+			const urlValidation = validateUrl(value);
+			if (!urlValidation.valid) throw new Error(urlValidation.error);
+			options.url = normalizeBaseUrl(value);
+			i++;
+		} else if (arg === `--auth`) {
+			const value = args[i + 1];
+			if (!value || value.startsWith(`--`)) throw new Error(`--auth requires a value\n  Example: --auth "Bearer my-token"`);
+			const authValidation = validateAuth(value);
+			if (!authValidation.valid) throw new Error(authValidation.error);
+			if (authValidation.warning) warnings.push(authValidation.warning);
+			options.auth = value;
+			i++;
+		} else remainingArgs.push(arg);
+	}
+	if (!options.url) {
+		const urlValidation = validateUrl(STREAM_URL);
+		if (!urlValidation.valid) throw new Error(`Invalid STREAM_URL environment variable: ${urlValidation.error}`);
+		options.url = normalizeBaseUrl(STREAM_URL);
+	}
+	if (!options.auth && STREAM_AUTH) {
+		const authValidation = validateAuth(STREAM_AUTH);
+		if (!authValidation.valid) throw new Error(`Invalid STREAM_AUTH environment variable: ${authValidation.error}`);
+		if (authValidation.warning) warnings.push(authValidation.warning);
+		options.auth = STREAM_AUTH;
+	}
+	return {
+		options,
+		remainingArgs,
+		warnings
+	};
+}
+function getErrorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function buildHeaders(options) {
+	return options.auth ? { Authorization: options.auth } : {};
+}
+function getUsageText() {
+	return `
 Usage:
   durable-stream create <stream_id>              Create a new stream
   durable-stream write <stream_id> <content>     Write content to a stream
@@ -101,6 +237,11 @@ Usage:
   durable-stream read <stream_id>                Follow a stream and write to stdout
   durable-stream delete <stream_id>              Delete a stream
 
+Global Options:
+  --url <url>             Stream server URL (overrides STREAM_URL env var)
+  --auth <value>          Authorization header value (e.g., "Bearer my-token")
+  --help, -h              Show this help message
+
 Write Options:
   --content-type <type>   Content-Type for the message (default: application/octet-stream)
   --json                  Write as JSON (input stored as single message)
@@ -108,167 +249,256 @@ Write Options:
 
 Environment Variables:
   STREAM_URL    Base URL of the stream server (default: http://localhost:4437)
-`);
+  STREAM_AUTH   Authorization header value (overridden by --auth flag)
+`;
+}
+function printUsage({ to = `stderr` } = {}) {
+	const out = to === `stderr` ? node_process.stderr : node_process.stdout;
+	out.write(getUsageText());
 }
-async function createStream(streamId) {
-	const url = `${STREAM_URL}/v1/stream/${streamId}`;
+async function createStream(baseUrl, streamId, headers) {
+	const url = `${baseUrl}/v1/stream/${streamId}`;
 	try {
 		await __durable_streams_client.DurableStream.create({
 			url,
+			headers,
 			contentType: `application/octet-stream`
 		});
-		console.log(`Created stream: ${streamId}`);
+		console.log(`Stream created successfully: "${streamId}"`);
+		console.log(`  URL: ${url}`);
 	} catch (error) {
-		if (error instanceof Error) node_process.stderr.write(`Error creating stream: ${error.message}\n`);
+		node_process.stderr.write(`Failed to create stream "${streamId}"\n`);
+		node_process.stderr.write(`  ${formatErrorMessage(getErrorMessage(error))}\n`);
 		process.exit(1);
 	}
 }
 /**
-* Append JSON data to a stream with one-level array flattening.
+* Format error messages from the server/client for better readability.
 */
-async function appendJson(stream, parsed) {
-	let count = 0;
-	for (const item of flattenJsonForAppend(parsed)) {
-		await stream.append(item);
-		count++;
+function formatErrorMessage(message) {
+	const httpMatch = message.match(/HTTP Error (\d+)/);
+	const statusCode = httpMatch?.[1];
+	if (statusCode) {
+		const status = parseInt(statusCode, 10);
+		const statusText = getHttpStatusText(status);
+		return message.replace(/HTTP Error \d+/, `${statusText} (${status})`);
 	}
-	return count;
+	return message;
 }
-async function writeStream(streamId, contentType, batchJson, content) {
-	const url = `${STREAM_URL}/v1/stream/${streamId}`;
+function getHttpStatusText(status) {
+	return node_http.STATUS_CODES[status] ?? `HTTP Error`;
+}
+/**
+* Append JSON data to a stream using batch semantics.
+* Arrays are flattened one level (each element becomes a separate message).
+* Non-array values are written as a single message.
+* Returns the number of messages written.
+*/
+async function appendJsonBatch(stream, parsed) {
+	const items = [...flattenJsonForAppend(parsed)];
+	for (const item of items) await stream.append(JSON.stringify(item));
+	return items.length;
+}
+/**
+* Read all data from stdin into a Buffer.
+*/
+async function readStdin() {
+	const chunks = [];
+	node_process.stdin.on(`data`, (chunk) => {
+		chunks.push(chunk);
+	});
+	await new Promise((resolve, reject) => {
+		node_process.stdin.on(`end`, resolve);
+		node_process.stdin.on(`error`, (err) => {
+			reject(new Error(`Failed to read from stdin: ${err.message}`));
+		});
+	});
+	return Buffer.concat(chunks);
+}
+/**
+* Process escape sequences in content string.
+*/
+function processEscapeSequences(content) {
+	return content.replace(/\\n/g, `\n`).replace(/\\t/g, `\t`).replace(/\\r/g, `\r`).replace(/\\\\/g, `\\`);
+}
+async function writeStream(baseUrl, streamId, contentType, batchJson, headers, content) {
+	const url = `${baseUrl}/v1/stream/${streamId}`;
 	const isJson = isJsonContentType(contentType);
+	let data;
+	let source;
+	if (content) {
+		data = processEscapeSequences(content);
+		source = `argument`;
+	} else {
+		data = await readStdin();
+		source = `stdin`;
+		if (data.length === 0) {
+			node_process.stderr.write(`No data received from stdin\n`);
+			process.exit(1);
+		}
+	}
 	try {
 		const stream = new __durable_streams_client.DurableStream({
 			url,
+			headers,
 			contentType
 		});
-		if (content) {
-			const processedContent = content.replace(/\\n/g, `\n`).replace(/\\t/g, `\t`).replace(/\\r/g, `\r`).replace(/\\\\/g, `\\`);
-			if (isJson) {
-				const parsed = JSON.parse(processedContent);
-				if (batchJson) {
-					const count = await appendJson(stream, parsed);
-					console.log(`Wrote ${count} message(s) to ${streamId}`);
+		if (isJson) {
+			const jsonString = typeof data === `string` ? data : data.toString(`utf8`);
+			let parsed;
+			try {
+				parsed = JSON.parse(jsonString);
+			} catch (parseError) {
+				const parseMessage = parseError instanceof SyntaxError ? parseError.message : `Unknown parsing error`;
+				if (source === `argument`) {
+					const preview = jsonString.slice(0, 100);
+					const ellipsis = jsonString.length > 100 ? `...` : ``;
+					node_process.stderr.write(`Failed to parse JSON content\n`);
+					node_process.stderr.write(`  ${parseMessage}\n`);
+					node_process.stderr.write(`  Input: ${preview}${ellipsis}\n`);
 				} else {
-					await stream.append(parsed);
-					console.log(`Wrote 1 message to ${streamId}`);
+					node_process.stderr.write(`Failed to parse JSON from stdin\n`);
+					node_process.stderr.write(`  ${parseMessage}\n`);
 				}
-			} else {
-				await stream.append(processedContent);
-				console.log(`Wrote ${processedContent.length} bytes to ${streamId}`);
+				process.exit(1);
 			}
-		} else {
-			const chunks = [];
-			node_process.stdin.on(`data`, (chunk) => {
-				chunks.push(chunk);
-			});
-			await new Promise((resolve, reject) => {
-				node_process.stdin.on(`end`, resolve);
-				node_process.stdin.on(`error`, reject);
-			});
-			const data = Buffer.concat(chunks);
-			if (isJson) {
-				const parsed = JSON.parse(data.toString(`utf8`));
-				if (batchJson) {
-					const count = await appendJson(stream, parsed);
-					console.log(`Wrote ${count} message(s) to ${streamId}`);
-				} else {
-					await stream.append(parsed);
-					console.log(`Wrote 1 message to ${streamId}`);
-				}
+			if (batchJson) {
+				const count = await appendJsonBatch(stream, parsed);
+				console.log(`Wrote ${count} message${count !== 1 ? `s` : ``} to stream "${streamId}"`);
 			} else {
-				await stream.append(data);
-				console.log(`Wrote ${data.length} bytes to ${streamId}`);
+				await stream.append(JSON.stringify(parsed));
+				console.log(`Wrote 1 JSON message to stream "${streamId}"`);
 			}
+		} else {
+			await stream.append(data);
+			const byteCount = typeof data === `string` ? Buffer.byteLength(data, `utf8`) : data.length;
+			console.log(`Wrote ${formatBytes(byteCount)} to stream "${streamId}"`);
 		}
 	} catch (error) {
-		if (error instanceof Error) node_process.stderr.write(`Error writing to stream: ${error.message}\n`);
+		node_process.stderr.write(`Failed to write to stream "${streamId}"\n`);
+		node_process.stderr.write(`  ${formatErrorMessage(getErrorMessage(error))}\n`);
 		process.exit(1);
 	}
 }
-async function readStream(streamId) {
-	const url = `${STREAM_URL}/v1/stream/${streamId}`;
+function formatBytes(bytes) {
+	if (bytes === 1) return `1 byte`;
+	if (bytes < 1024) return `${bytes} bytes`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+async function readStream(baseUrl, streamId, headers) {
+	const url = `${baseUrl}/v1/stream/${streamId}`;
 	try {
-		const stream = new __durable_streams_client.DurableStream({ url });
-		const res = await stream.stream({ live: `auto` });
+		const stream = new __durable_streams_client.DurableStream({
+			url,
+			headers
+		});
+		const res = await stream.stream({ live: true });
 		for await (const chunk of res.bodyStream()) if (chunk.length > 0) node_process.stdout.write(chunk);
 	} catch (error) {
-		if (error instanceof Error) node_process.stderr.write(`Error reading stream: ${error.message}\n`);
+		node_process.stderr.write(`Failed to read stream "${streamId}"\n`);
+		node_process.stderr.write(`  ${formatErrorMessage(getErrorMessage(error))}\n`);
 		process.exit(1);
 	}
 }
-async function deleteStream(streamId) {
-	const url = `${STREAM_URL}/v1/stream/${streamId}`;
+async function deleteStream(baseUrl, streamId, headers) {
+	const url = `${baseUrl}/v1/stream/${streamId}`;
 	try {
-		const stream = new __durable_streams_client.DurableStream({ url });
+		const stream = new __durable_streams_client.DurableStream({
+			url,
+			headers
+		});
 		await stream.delete();
-		console.log(`Deleted stream: ${streamId}`);
+		console.log(`Stream deleted successfully: "${streamId}"`);
 	} catch (error) {
-		if (error instanceof Error) node_process.stderr.write(`Error deleting stream: ${error.message}\n`);
+		node_process.stderr.write(`Failed to delete stream "${streamId}"\n`);
+		node_process.stderr.write(`  ${formatErrorMessage(getErrorMessage(error))}\n`);
 		process.exit(1);
 	}
 }
 async function main() {
-	const args = process.argv.slice(2);
+	const rawArgs = process.argv.slice(2);
+	if (rawArgs.includes(`--help`) || rawArgs.includes(`-h`)) {
+		printUsage({ to: `stdout` });
+		process.exit(0);
+	}
+	let options;
+	let args;
+	let warnings;
+	try {
+		const parsed = parseGlobalOptions(rawArgs);
+		options = parsed.options;
+		args = parsed.remainingArgs;
+		warnings = parsed.warnings;
+	} catch (error) {
+		node_process.stderr.write(`Error: ${getErrorMessage(error)}\n`);
+		process.exit(1);
+	}
+	for (const warning of warnings) node_process.stderr.write(`${warning}\n`);
+	const headers = buildHeaders(options);
 	if (args.length < 1) {
+		node_process.stderr.write(`Error: No command specified\n`);
 		printUsage();
 		process.exit(1);
 	}
 	const command = args[0];
+	function getStreamId() {
+		if (args.length < 2) {
+			node_process.stderr.write(`Error: Missing stream_id\n`);
+			node_process.stderr.write(`  Usage: durable-stream ${command} <stream_id>\n`);
+			process.exit(1);
+		}
+		const streamId = args[1];
+		const validation = validateStreamId(streamId);
+		if (!validation.valid) {
+			node_process.stderr.write(`Error: ${validation.error}\n`);
+			process.exit(1);
+		}
+		return streamId;
+	}
 	switch (command) {
 		case `create`: {
-			if (args.length < 2) {
-				node_process.stderr.write(`Error: stream_id required\n`);
-				printUsage();
-				process.exit(1);
-			}
-			await createStream(args[1]);
+			const streamId = getStreamId();
+			await createStream(options.url, streamId, headers);
 			break;
 		}
 		case `write`: {
-			if (args.length < 2) {
-				node_process.stderr.write(`Error: stream_id required\n`);
-				printUsage();
-				process.exit(1);
-			}
-			const streamId = args[1];
+			const streamId = getStreamId();
 			let parsed;
 			try {
 				parsed = parseWriteArgs(args.slice(2));
 			} catch (error) {
-				if (error instanceof Error) node_process.stderr.write(`Error: ${error.message}\n`);
+				node_process.stderr.write(`Error: ${getErrorMessage(error)}\n`);
 				process.exit(1);
 			}
-			if (!node_process.stdin.isTTY) await writeStream(streamId, parsed.contentType, parsed.batchJson);
-			else if (parsed.content) await writeStream(streamId, parsed.contentType, parsed.batchJson, parsed.content);
+			const hasContent = parsed.content || !node_process.stdin.isTTY;
+			if (hasContent) await writeStream(options.url, streamId, parsed.contentType, parsed.batchJson, headers, parsed.content || void 0);
 			else {
-				node_process.stderr.write(`Error: content required (provide as argument or pipe to stdin)\n`);
-				printUsage();
+				node_process.stderr.write(`Error: No content provided\n`);
+				node_process.stderr.write(`  Provide content as an argument or pipe from stdin:\n`);
+				node_process.stderr.write(`    durable-stream write ${streamId} "your content here"\n`);
+				node_process.stderr.write(`    echo "content" | durable-stream write ${streamId}\n`);
 				process.exit(1);
 			}
 			break;
 		}
 		case `read`: {
-			if (args.length < 2) {
-				node_process.stderr.write(`Error: stream_id required\n`);
-				printUsage();
-				process.exit(1);
-			}
-			await readStream(args[1]);
+			const streamId = getStreamId();
+			await readStream(options.url, streamId, headers);
 			break;
 		}
 		case `delete`: {
-			if (args.length < 2) {
-				node_process.stderr.write(`Error: stream_id required\n`);
-				printUsage();
-				process.exit(1);
-			}
-			await deleteStream(args[1]);
+			const streamId = getStreamId();
+			await deleteStream(options.url, streamId, headers);
 			break;
 		}
 		default:
-			node_process.stderr.write(`Error: unknown command '${command}'\n`);
-			printUsage();
+			if (command?.startsWith(`-`)) node_process.stderr.write(`Error: Unknown option "${command}"\n`);
+			else {
+				node_process.stderr.write(`Error: Unknown command "${command}"\n`);
+				node_process.stderr.write(`  Available commands: create, write, read, delete\n`);
+			}
+			node_process.stderr.write(`  Run "durable-stream --help" for usage information\n`);
 			process.exit(1);
 	}
 }
@@ -279,11 +509,18 @@ function isMainModule() {
 	return scriptPath === modulePath;
 }
 if (isMainModule()) main().catch((error) => {
-	node_process.stderr.write(`Fatal error: ${error.message}\n`);
+	node_process.stderr.write(`Fatal error: ${getErrorMessage(error)}\n`);
 	process.exit(1);
 });
 
 //#endregion
+exports.buildHeaders = buildHeaders
 exports.flattenJsonForAppend = flattenJsonForAppend
+exports.getUsageText = getUsageText
 exports.isJsonContentType = isJsonContentType
-exports.parseWriteArgs = parseWriteArgs
+exports.normalizeBaseUrl = normalizeBaseUrl
+exports.parseGlobalOptions = parseGlobalOptions
+exports.parseWriteArgs = parseWriteArgs
+exports.validateAuth = validateAuth
+exports.validateStreamId = validateStreamId
+exports.validateUrl = validateUrl

package/dist/index.d.cts

@@ -30,4 +30,56 @@ interface ParsedWriteArgs {
 declare function parseWriteArgs(args: Array<string>): ParsedWriteArgs;
 
 //#endregion
-export { ParsedWriteArgs, flattenJsonForAppend, isJsonContentType, parseWriteArgs };
+//#region src/validation.d.ts
+/**
+* Validation utilities for CLI options with helpful error messages.
+*/
+interface ValidationResult {
+  valid: boolean;
+  error?: string;
+  warning?: string;
+}
+/**
+* Validate a URL string.
+* Must be a valid HTTP or HTTPS URL.
+*/
+declare function validateUrl(url: string): ValidationResult;
+/**
+* Normalize a base URL by removing trailing slashes.
+* This prevents double-slashes when appending paths (e.g., "http://host/" + "/v1/...").
+*/
+declare function normalizeBaseUrl(url: string): string;
+/**
+* Validate an authorization header value.
+* Returns valid=true for any non-empty value, but includes a warning
+* if the value doesn't match common auth schemes (Bearer, Basic, ApiKey, Token).
+*/
+declare function validateAuth(auth: string): ValidationResult;
+/**
+* Validate a stream ID.
+* Must be 1-256 characters containing only: letters, numbers, underscores,
+* hyphens, dots, and colons (URL-safe characters).
+*/
+declare function validateStreamId(streamId: string): ValidationResult;
+
+//#endregion
+//#region src/index.d.ts
+interface GlobalOptions {
+  url?: string;
+  auth?: string;
+}
+/**
+* Parse global options (--url, --auth) from args.
+* Falls back to STREAM_URL/STREAM_AUTH env vars when flags not provided.
+* Returns the parsed options, remaining args, and any warnings.
+*/
+declare function parseGlobalOptions(args: Array<string>): {
+  options: GlobalOptions;
+  remainingArgs: Array<string>;
+  warnings: Array<string>;
+};
+declare function buildHeaders(options: GlobalOptions): Record<string, string>;
+declare function getUsageText(): string;
+
+//#endregion
+export { GlobalOptions, ParsedWriteArgs, buildHeaders, flattenJsonForAppend, getUsageText, isJsonContentType, normalizeBaseUrl, parseGlobalOptions, parseWriteArgs, validateAuth, validateStreamId, validateUrl };

package/dist/index.d.ts

@@ -30,4 +30,56 @@ interface ParsedWriteArgs {
 declare function parseWriteArgs(args: Array<string>): ParsedWriteArgs;
 
 //#endregion
-export { ParsedWriteArgs, flattenJsonForAppend, isJsonContentType, parseWriteArgs };
+//#region src/validation.d.ts
+/**
+* Validation utilities for CLI options with helpful error messages.
+*/
+interface ValidationResult {
+  valid: boolean;
+  error?: string;
+  warning?: string;
+}
+/**
+* Validate a URL string.
+* Must be a valid HTTP or HTTPS URL.
+*/
+declare function validateUrl(url: string): ValidationResult;
+/**
+* Normalize a base URL by removing trailing slashes.
+* This prevents double-slashes when appending paths (e.g., "http://host/" + "/v1/...").
+*/
+declare function normalizeBaseUrl(url: string): string;
+/**
+* Validate an authorization header value.
+* Returns valid=true for any non-empty value, but includes a warning
+* if the value doesn't match common auth schemes (Bearer, Basic, ApiKey, Token).
+*/
+declare function validateAuth(auth: string): ValidationResult;
+/**
+* Validate a stream ID.
+* Must be 1-256 characters containing only: letters, numbers, underscores,
+* hyphens, dots, and colons (URL-safe characters).
+*/
+declare function validateStreamId(streamId: string): ValidationResult;
+
+//#endregion
+//#region src/index.d.ts
+interface GlobalOptions {
+  url?: string;
+  auth?: string;
+}
+/**
+* Parse global options (--url, --auth) from args.
+* Falls back to STREAM_URL/STREAM_AUTH env vars when flags not provided.
+* Returns the parsed options, remaining args, and any warnings.
+*/
+declare function parseGlobalOptions(args: Array<string>): {
+  options: GlobalOptions;
+  remainingArgs: Array<string>;
+  warnings: Array<string>;
+};
+declare function buildHeaders(options: GlobalOptions): Record<string, string>;
+declare function getUsageText(): string;
+
+//#endregion
+export { GlobalOptions, ParsedWriteArgs, buildHeaders, flattenJsonForAppend, getUsageText, isJsonContentType, normalizeBaseUrl, parseGlobalOptions, parseWriteArgs, validateAuth, validateStreamId, validateUrl };

package/dist/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { STATUS_CODES } from "node:http";
 import { resolve } from "node:path";
 import { stderr, stdin, stdout } from "node:process";
 import { fileURLToPath } from "node:url";
@@ -65,11 +66,146 @@ function parseWriteArgs(args) {
 	};
 }
 
+//#endregion
+//#region src/validation.ts
+/**
+* Validate a URL string.
+* Must be a valid HTTP or HTTPS URL.
+*/
+function validateUrl(url) {
+	if (!url || !url.trim()) return {
+		valid: false,
+		error: `URL cannot be empty`
+	};
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return {
+			valid: false,
+			error: `Invalid URL format: "${url}"\n  Expected format: http://host:port or https://host:port`
+		};
+	}
+	if (parsed.protocol !== `http:` && parsed.protocol !== `https:`) return {
+		valid: false,
+		error: `Invalid URL protocol: "${parsed.protocol}"\n  Only http:// and https:// are supported`
+	};
+	if (!parsed.hostname) return {
+		valid: false,
+		error: `URL must include a hostname: "${url}"`
+	};
+	return { valid: true };
+}
+/**
+* Normalize a base URL by removing trailing slashes.
+* This prevents double-slashes when appending paths (e.g., "http://host/" + "/v1/...").
+*/
+function normalizeBaseUrl(url) {
+	return url.replace(/\/+$/, ``);
+}
+/**
+* Validate an authorization header value.
+* Returns valid=true for any non-empty value, but includes a warning
+* if the value doesn't match common auth schemes (Bearer, Basic, ApiKey, Token).
+*/
+function validateAuth(auth) {
+	if (!auth || !auth.trim()) return {
+		valid: false,
+		error: `Authorization value cannot be empty`
+	};
+	const trimmed = auth.trim();
+	const lowerTrimmed = trimmed.toLowerCase();
+	const hasScheme = [
+		`bearer `,
+		`basic `,
+		`apikey `,
+		`token `
+	].some((scheme) => lowerTrimmed.startsWith(scheme));
+	if (!hasScheme && !trimmed.includes(` `)) return {
+		valid: true,
+		warning: `Warning: Authorization value doesn't match common formats.\n  Expected: "Bearer <token>", "Basic <credentials>", or "ApiKey <key>"`
+	};
+	return { valid: true };
+}
+/**
+* Validate a stream ID.
+* Must be 1-256 characters containing only: letters, numbers, underscores,
+* hyphens, dots, and colons (URL-safe characters).
+*/
+function validateStreamId(streamId) {
+	if (!streamId || !streamId.trim()) return {
+		valid: false,
+		error: `Stream ID cannot be empty`
+	};
+	const validPattern = /^[a-zA-Z0-9_\-.:]+$/;
+	if (!validPattern.test(streamId)) return {
+		valid: false,
+		error: `Invalid stream ID: "${streamId}"\n  Stream IDs can only contain letters, numbers, underscores, hyphens, dots, and colons`
+	};
+	if (streamId.length > 256) return {
+		valid: false,
+		error: `Stream ID too long (${streamId.length} chars)\n  Maximum length is 256 characters`
+	};
+	return { valid: true };
+}
+
 //#endregion
 //#region src/index.ts
 const STREAM_URL = process.env.STREAM_URL || `http://localhost:4437`;
-function printUsage() {
-	console.error(`
+const STREAM_AUTH = process.env.STREAM_AUTH;
+/**
+* Parse global options (--url, --auth) from args.
+* Falls back to STREAM_URL/STREAM_AUTH env vars when flags not provided.
+* Returns the parsed options, remaining args, and any warnings.
+*/
+function parseGlobalOptions(args) {
+	const options = {};
+	const remainingArgs = [];
+	const warnings = [];
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === `--url`) {
+			const value = args[i + 1];
+			if (!value || value.startsWith(`--`)) throw new Error(`--url requires a value\n  Example: --url "http://localhost:4437"`);
+			const urlValidation = validateUrl(value);
+			if (!urlValidation.valid) throw new Error(urlValidation.error);
+			options.url = normalizeBaseUrl(value);
+			i++;
+		} else if (arg === `--auth`) {
+			const value = args[i + 1];
+			if (!value || value.startsWith(`--`)) throw new Error(`--auth requires a value\n  Example: --auth "Bearer my-token"`);
+			const authValidation = validateAuth(value);
+			if (!authValidation.valid) throw new Error(authValidation.error);
+			if (authValidation.warning) warnings.push(authValidation.warning);
+			options.auth = value;
+			i++;
+		} else remainingArgs.push(arg);
+	}
+	if (!options.url) {
+		const urlValidation = validateUrl(STREAM_URL);
+		if (!urlValidation.valid) throw new Error(`Invalid STREAM_URL environment variable: ${urlValidation.error}`);
+		options.url = normalizeBaseUrl(STREAM_URL);
+	}
+	if (!options.auth && STREAM_AUTH) {
+		const authValidation = validateAuth(STREAM_AUTH);
+		if (!authValidation.valid) throw new Error(`Invalid STREAM_AUTH environment variable: ${authValidation.error}`);
+		if (authValidation.warning) warnings.push(authValidation.warning);
+		options.auth = STREAM_AUTH;
+	}
+	return {
+		options,
+		remainingArgs,
+		warnings
+	};
+}
+function getErrorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function buildHeaders(options) {
+	return options.auth ? { Authorization: options.auth } : {};
+}
+function getUsageText() {
+	return `
 Usage:
   durable-stream create <stream_id>              Create a new stream
   durable-stream write <stream_id> <content>     Write content to a stream
@@ -77,6 +213,11 @@ Usage:
   durable-stream read <stream_id>                Follow a stream and write to stdout
   durable-stream delete <stream_id>              Delete a stream
 
+Global Options:
+  --url <url>             Stream server URL (overrides STREAM_URL env var)
+  --auth <value>          Authorization header value (e.g., "Bearer my-token")
+  --help, -h              Show this help message
+
 Write Options:
   --content-type <type>   Content-Type for the message (default: application/octet-stream)
   --json                  Write as JSON (input stored as single message)
@@ -84,167 +225,256 @@ Write Options:
 
 Environment Variables:
   STREAM_URL    Base URL of the stream server (default: http://localhost:4437)
-`);
+  STREAM_AUTH   Authorization header value (overridden by --auth flag)
+`;
+}
+function printUsage({ to = `stderr` } = {}) {
+	const out = to === `stderr` ? stderr : stdout;
+	out.write(getUsageText());
 }
-async function createStream(streamId) {
-	const url = `${STREAM_URL}/v1/stream/${streamId}`;
+async function createStream(baseUrl, streamId, headers) {
+	const url = `${baseUrl}/v1/stream/${streamId}`;
 	try {
 		await DurableStream.create({
 			url,
+			headers,
 			contentType: `application/octet-stream`
 		});
-		console.log(`Created stream: ${streamId}`);
+		console.log(`Stream created successfully: "${streamId}"`);
+		console.log(`  URL: ${url}`);
 	} catch (error) {
-		if (error instanceof Error) stderr.write(`Error creating stream: ${error.message}\n`);
+		stderr.write(`Failed to create stream "${streamId}"\n`);
+		stderr.write(`  ${formatErrorMessage(getErrorMessage(error))}\n`);
 		process.exit(1);
 	}
 }
 /**
-* Append JSON data to a stream with one-level array flattening.
+* Format error messages from the server/client for better readability.
 */
-async function appendJson(stream, parsed) {
-	let count = 0;
-	for (const item of flattenJsonForAppend(parsed)) {
-		await stream.append(item);
-		count++;
+function formatErrorMessage(message) {
+	const httpMatch = message.match(/HTTP Error (\d+)/);
+	const statusCode = httpMatch?.[1];
+	if (statusCode) {
+		const status = parseInt(statusCode, 10);
+		const statusText = getHttpStatusText(status);
+		return message.replace(/HTTP Error \d+/, `${statusText} (${status})`);
 	}
-	return count;
+	return message;
 }
-async function writeStream(streamId, contentType, batchJson, content) {
-	const url = `${STREAM_URL}/v1/stream/${streamId}`;
+function getHttpStatusText(status) {
+	return STATUS_CODES[status] ?? `HTTP Error`;
+}
+/**
+* Append JSON data to a stream using batch semantics.
+* Arrays are flattened one level (each element becomes a separate message).
+* Non-array values are written as a single message.
+* Returns the number of messages written.
+*/
+async function appendJsonBatch(stream, parsed) {
+	const items = [...flattenJsonForAppend(parsed)];
+	for (const item of items) await stream.append(JSON.stringify(item));
+	return items.length;
+}
+/**
+* Read all data from stdin into a Buffer.
+*/
+async function readStdin() {
+	const chunks = [];
+	stdin.on(`data`, (chunk) => {
+		chunks.push(chunk);
+	});
+	await new Promise((resolve$1, reject) => {
+		stdin.on(`end`, resolve$1);
+		stdin.on(`error`, (err) => {
+			reject(new Error(`Failed to read from stdin: ${err.message}`));
+		});
+	});
+	return Buffer.concat(chunks);
+}
+/**
+* Process escape sequences in content string.
+*/
+function processEscapeSequences(content) {
+	return content.replace(/\\n/g, `\n`).replace(/\\t/g, `\t`).replace(/\\r/g, `\r`).replace(/\\\\/g, `\\`);
+}
+async function writeStream(baseUrl, streamId, contentType, batchJson, headers, content) {
+	const url = `${baseUrl}/v1/stream/${streamId}`;
 	const isJson = isJsonContentType(contentType);
+	let data;
+	let source;
+	if (content) {
+		data = processEscapeSequences(content);
+		source = `argument`;
+	} else {
+		data = await readStdin();
+		source = `stdin`;
+		if (data.length === 0) {
+			stderr.write(`No data received from stdin\n`);
+			process.exit(1);
+		}
+	}
 	try {
 		const stream = new DurableStream({
 			url,
+			headers,
 			contentType
 		});
-		if (content) {
-			const processedContent = content.replace(/\\n/g, `\n`).replace(/\\t/g, `\t`).replace(/\\r/g, `\r`).replace(/\\\\/g, `\\`);
-			if (isJson) {
-				const parsed = JSON.parse(processedContent);
-				if (batchJson) {
-					const count = await appendJson(stream, parsed);
-					console.log(`Wrote ${count} message(s) to ${streamId}`);
+		if (isJson) {
+			const jsonString = typeof data === `string` ? data : data.toString(`utf8`);
+			let parsed;
+			try {
+				parsed = JSON.parse(jsonString);
+			} catch (parseError) {
+				const parseMessage = parseError instanceof SyntaxError ? parseError.message : `Unknown parsing error`;
+				if (source === `argument`) {
+					const preview = jsonString.slice(0, 100);
+					const ellipsis = jsonString.length > 100 ? `...` : ``;
+					stderr.write(`Failed to parse JSON content\n`);
+					stderr.write(`  ${parseMessage}\n`);
+					stderr.write(`  Input: ${preview}${ellipsis}\n`);
 				} else {
-					await stream.append(parsed);
-					console.log(`Wrote 1 message to ${streamId}`);
+					stderr.write(`Failed to parse JSON from stdin\n`);
+					stderr.write(`  ${parseMessage}\n`);
 				}
-			} else {
-				await stream.append(processedContent);
-				console.log(`Wrote ${processedContent.length} bytes to ${streamId}`);
+				process.exit(1);
 			}
-		} else {
-			const chunks = [];
-			stdin.on(`data`, (chunk) => {
-				chunks.push(chunk);
-			});
-			await new Promise((resolve$1, reject) => {
-				stdin.on(`end`, resolve$1);
-				stdin.on(`error`, reject);
-			});
-			const data = Buffer.concat(chunks);
-			if (isJson) {
-				const parsed = JSON.parse(data.toString(`utf8`));
-				if (batchJson) {
-					const count = await appendJson(stream, parsed);
-					console.log(`Wrote ${count} message(s) to ${streamId}`);
-				} else {
-					await stream.append(parsed);
-					console.log(`Wrote 1 message to ${streamId}`);
-				}
+			if (batchJson) {
+				const count = await appendJsonBatch(stream, parsed);
+				console.log(`Wrote ${count} message${count !== 1 ? `s` : ``} to stream "${streamId}"`);
 			} else {
-				await stream.append(data);
-				console.log(`Wrote ${data.length} bytes to ${streamId}`);
+				await stream.append(JSON.stringify(parsed));
+				console.log(`Wrote 1 JSON message to stream "${streamId}"`);
 			}
+		} else {
+			await stream.append(data);
+			const byteCount = typeof data === `string` ? Buffer.byteLength(data, `utf8`) : data.length;
+			console.log(`Wrote ${formatBytes(byteCount)} to stream "${streamId}"`);
 		}
 	} catch (error) {
-		if (error instanceof Error) stderr.write(`Error writing to stream: ${error.message}\n`);
+		stderr.write(`Failed to write to stream "${streamId}"\n`);
+		stderr.write(`  ${formatErrorMessage(getErrorMessage(error))}\n`);
 		process.exit(1);
 	}
 }
-async function readStream(streamId) {
-	const url = `${STREAM_URL}/v1/stream/${streamId}`;
+function formatBytes(bytes) {
+	if (bytes === 1) return `1 byte`;
+	if (bytes < 1024) return `${bytes} bytes`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+async function readStream(baseUrl, streamId, headers) {
+	const url = `${baseUrl}/v1/stream/${streamId}`;
 	try {
-		const stream = new DurableStream({ url });
-		const res = await stream.stream({ live: `auto` });
+		const stream = new DurableStream({
+			url,
+			headers
+		});
+		const res = await stream.stream({ live: true });
 		for await (const chunk of res.bodyStream()) if (chunk.length > 0) stdout.write(chunk);
 	} catch (error) {
-		if (error instanceof Error) stderr.write(`Error reading stream: ${error.message}\n`);
+		stderr.write(`Failed to read stream "${streamId}"\n`);
+		stderr.write(`  ${formatErrorMessage(getErrorMessage(error))}\n`);
 		process.exit(1);
 	}
 }
-async function deleteStream(streamId) {
-	const url = `${STREAM_URL}/v1/stream/${streamId}`;
+async function deleteStream(baseUrl, streamId, headers) {
+	const url = `${baseUrl}/v1/stream/${streamId}`;
 	try {
-		const stream = new DurableStream({ url });
+		const stream = new DurableStream({
+			url,
+			headers
+		});
 		await stream.delete();
-		console.log(`Deleted stream: ${streamId}`);
+		console.log(`Stream deleted successfully: "${streamId}"`);
 	} catch (error) {
-		if (error instanceof Error) stderr.write(`Error deleting stream: ${error.message}\n`);
+		stderr.write(`Failed to delete stream "${streamId}"\n`);
+		stderr.write(`  ${formatErrorMessage(getErrorMessage(error))}\n`);
 		process.exit(1);
 	}
 }
 async function main() {
-	const args = process.argv.slice(2);
+	const rawArgs = process.argv.slice(2);
+	if (rawArgs.includes(`--help`) || rawArgs.includes(`-h`)) {
+		printUsage({ to: `stdout` });
+		process.exit(0);
+	}
+	let options;
+	let args;
+	let warnings;
+	try {
+		const parsed = parseGlobalOptions(rawArgs);
+		options = parsed.options;
+		args = parsed.remainingArgs;
+		warnings = parsed.warnings;
+	} catch (error) {
+		stderr.write(`Error: ${getErrorMessage(error)}\n`);
+		process.exit(1);
+	}
+	for (const warning of warnings) stderr.write(`${warning}\n`);
+	const headers = buildHeaders(options);
 	if (args.length < 1) {
+		stderr.write(`Error: No command specified\n`);
 		printUsage();
 		process.exit(1);
 	}
 	const command = args[0];
+	function getStreamId() {
+		if (args.length < 2) {
+			stderr.write(`Error: Missing stream_id\n`);
+			stderr.write(`  Usage: durable-stream ${command} <stream_id>\n`);
+			process.exit(1);
+		}
+		const streamId = args[1];
+		const validation = validateStreamId(streamId);
+		if (!validation.valid) {
+			stderr.write(`Error: ${validation.error}\n`);
+			process.exit(1);
+		}
+		return streamId;
+	}
 	switch (command) {
 		case `create`: {
-			if (args.length < 2) {
-				stderr.write(`Error: stream_id required\n`);
-				printUsage();
-				process.exit(1);
-			}
-			await createStream(args[1]);
+			const streamId = getStreamId();
+			await createStream(options.url, streamId, headers);
 			break;
 		}
 		case `write`: {
-			if (args.length < 2) {
-				stderr.write(`Error: stream_id required\n`);
-				printUsage();
-				process.exit(1);
-			}
-			const streamId = args[1];
+			const streamId = getStreamId();
 			let parsed;
 			try {
 				parsed = parseWriteArgs(args.slice(2));
 			} catch (error) {
-				if (error instanceof Error) stderr.write(`Error: ${error.message}\n`);
+				stderr.write(`Error: ${getErrorMessage(error)}\n`);
 				process.exit(1);
 			}
-			if (!stdin.isTTY) await writeStream(streamId, parsed.contentType, parsed.batchJson);
-			else if (parsed.content) await writeStream(streamId, parsed.contentType, parsed.batchJson, parsed.content);
+			const hasContent = parsed.content || !stdin.isTTY;
+			if (hasContent) await writeStream(options.url, streamId, parsed.contentType, parsed.batchJson, headers, parsed.content || void 0);
 			else {
-				stderr.write(`Error: content required (provide as argument or pipe to stdin)\n`);
-				printUsage();
+				stderr.write(`Error: No content provided\n`);
+				stderr.write(`  Provide content as an argument or pipe from stdin:\n`);
+				stderr.write(`    durable-stream write ${streamId} "your content here"\n`);
+				stderr.write(`    echo "content" | durable-stream write ${streamId}\n`);
 				process.exit(1);
 			}
 			break;
 		}
 		case `read`: {
-			if (args.length < 2) {
-				stderr.write(`Error: stream_id required\n`);
-				printUsage();
-				process.exit(1);
-			}
-			await readStream(args[1]);
+			const streamId = getStreamId();
+			await readStream(options.url, streamId, headers);
 			break;
 		}
 		case `delete`: {
-			if (args.length < 2) {
-				stderr.write(`Error: stream_id required\n`);
-				printUsage();
-				process.exit(1);
-			}
-			await deleteStream(args[1]);
+			const streamId = getStreamId();
+			await deleteStream(options.url, streamId, headers);
 			break;
 		}
 		default:
-			stderr.write(`Error: unknown command '${command}'\n`);
-			printUsage();
+			if (command?.startsWith(`-`)) stderr.write(`Error: Unknown option "${command}"\n`);
+			else {
+				stderr.write(`Error: Unknown command "${command}"\n`);
+				stderr.write(`  Available commands: create, write, read, delete\n`);
+			}
+			stderr.write(`  Run "durable-stream --help" for usage information\n`);
 			process.exit(1);
 	}
 }
@@ -255,9 +485,9 @@ function isMainModule() {
 	return scriptPath === modulePath;
 }
 if (isMainModule()) main().catch((error) => {
-	stderr.write(`Fatal error: ${error.message}\n`);
+	stderr.write(`Fatal error: ${getErrorMessage(error)}\n`);
 	process.exit(1);
 });
 
 //#endregion
-export { flattenJsonForAppend, isJsonContentType, parseWriteArgs };
+export { buildHeaders, flattenJsonForAppend, getUsageText, isJsonContentType, normalizeBaseUrl, parseGlobalOptions, parseWriteArgs, validateAuth, validateStreamId, validateUrl };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@durable-streams/cli",
   "description": "CLI tool for working with Durable Streams",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "author": "Durable Stream contributors",
   "bin": {
     "cli": "./dist/index.js",
@@ -12,7 +12,7 @@
     "url": "https://github.com/durable-streams/durable-streams/issues"
   },
   "dependencies": {
-    "@durable-streams/client": "0.1.5"
+    "@durable-streams/client": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.21",
@@ -20,7 +20,7 @@
     "tsx": "^4.19.2",
     "typescript": "^5.5.2",
     "vitest": "^3.1.3",
-    "@durable-streams/server": "0.1.6"
+    "@durable-streams/server": "0.1.7"
   },
   "engines": {
     "node": ">=18.0.0"