npm package: @llms-sdk/cli
Description: Type-safe CLI argument parsing with provider/model validation and schema introspection
Author: Lenny Miller
Latest version: 2.2.0

# @llms-sdk/cli

Type-safe CLI argument parsing with provider/model validation and schema introspection for LLMS SDK applications.

## Features

- **Type-safe argument parsing** with automatic validation
- **Provider and model validation** for LLM integrations
- **Schema introspection** for runtime type checking
- **Commander.js integration** for robust CLI applications
- **Zod schema validation** for runtime safety
- **Built-in help generation** with proper documentation

## Installation

```bash
npm install @llms-sdk/cli
```

## Quick Start

```typescript
import { createCLI, defineCliSchema } from "@llms-sdk/cli";

// Define your CLI schema
const schema = defineCliSchema({
	provider: {
		type: "string",
		choices: ["anthropic", "openai", "google"],
		description: "LLM provider to use",
		required: true,
	},
	model: {
		type: "string",
		description: "Model name",
		default: "claude-3-5-sonnet-20241022",
	},
	temperature: {
		type: "number",
		description: "Sampling temperature",
		default: 0.7,
		min: 0,
		max: 2,
	},
});

// Create CLI instance
const cli = createCLI(schema);

// Parse arguments with type safety
const args = cli.parse(process.argv);

console.log(args.provider); // TypeScript knows this is 'anthropic' | 'openai' | 'google'
console.log(args.model); // TypeScript knows this is string
console.log(args.temperature); // TypeScript knows this is number
```

## Advanced Usage

### Provider/Model Validation

```typescript
import { validateProvider, validateModel } from "@llms-sdk/cli";

// Validate provider exists
if (!validateProvider(args.provider)) {
	console.error(`Invalid provider: ${args.provider}`);
	process.exit(1);
}

// Validate model for specific provider
if (!validateModel(args.provider, args.model)) {
	console.error(`Invalid model ${args.model} for provider ${args.provider}`);
	process.exit(1);
}
```

### Schema Introspection

```typescript
import { introspectSchema } from "@llms-sdk/cli";

const schemaInfo = introspectSchema(schema);
console.log("Available options:", schemaInfo.fields);
console.log("Required fields:", schemaInfo.required);
console.log("Default values:", schemaInfo.defaults);
```

### Custom Validation

```typescript
const schema = defineCliSchema({
	input: {
		type: "string",
		description: "Input file path",
		validate: (value) => {
			if (!fs.existsSync(value)) {
				throw new Error(`File does not exist: ${value}`);
			}
			return value;
		},
	},
});
```

## API Reference

### `createCLI(schema)`

Creates a new CLI instance with the given schema.

**Parameters:**

- `schema` - CLI schema definition

**Returns:** CLI instance with type-safe `parse()` method

### `defineCliSchema(definition)`

Defines a CLI schema with type safety and validation.

**Parameters:**

- `definition` - Schema definition object

**Returns:** Typed schema for use with `createCLI()`

### `validateProvider(provider)`

Validates if a provider is supported by LLMS SDK.

**Parameters:**

- `provider` - Provider name to validate

**Returns:** `boolean`

### `validateModel(provider, model)`

Validates if a model is available for the specified provider.

**Parameters:**

- `provider` - Provider name
- `model` - Model name to validate

**Returns:** `boolean`

### `introspectSchema(schema)`

Introspects a CLI schema to extract metadata.

**Parameters:**

- `schema` - CLI schema to introspect

**Returns:** Schema metadata object

## Integration with LLMS SDK

This package is designed to work seamlessly with other LLMS SDK packages:

```typescript
import { createCLI } from "@llms-sdk/cli";
import { LLMSClient } from "@llms-sdk/core";

const args = cli.parse(process.argv);

const client = new LLMSClient({
	provider: args.provider,
	model: args.model,
	temperature: args.temperature,
});
```

## License

MIT

## Contributing

See the main [LLMS SDK repository](https://github.com/lennylmiller/llms-sdk) for contribution guidelines.