---
sidebar_label: "CLI Reference"
sidebar_custom_props:
  section: "Templates"
  section_position: 1
---

{/*

CLI Reference pages provide comprehensive documentation for command-line tools, including all 
commands, subcommands, options, and flags. Organize by command hierarchy and include detailed 
explanations of each option's behavior.

*/}

# CLI Reference Template

Complete reference for all command-line interface commands, options, and usage patterns.

## Global Options

These options are available for all commands:

| Option             | Description                              |
|--------------------|------------------------------------------|
| `--version`        | Display version information              |
| `--help, -h`       | Show help for any command                |
| `--verbose, -v`    | Enable verbose output                    |
| `--quiet, -q`      | Suppress non-error output                |
| `--config <path>`  | Specify custom configuration file path   |
| `--output, -o <format>` | Output format: `json`, `yaml`, `table` |

## Commands

### `init`

Initialize a new project or configuration.

**Usage:**

```bash
command init [options]
```

**Options:**

| Option              | Description                           | Default    |
|---------------------|---------------------------------------|------------|
| `--name <name>`     | Project name                          | Current directory name |
| `--template <type>` | Template to use (`basic`, `advanced`) | `basic`    |
| `--force, -f`       | Overwrite existing files              | `false`    |

**Examples:**

```bash
# Initialize with defaults
command init

# Initialize with custom name and template
command init --name my-project --template advanced

# Force initialization (overwrite existing)
command init --force
```

### `create`

Create a new resource.

**Usage:**

```bash
command create <resource-type> <name> [options]
```

**Parameters:**

| Parameter         | Type     | Required | Description                          | Default |
|-------------------|----------|----------|--------------------------------------|---------|
| `resource-type`   | argument | Yes      | Type of resource to create           | -       |
| `name`            | argument | Yes      | Name for the new resource            | -       |
| `--description <text>` | option | No  | Resource description                 | -       |
| `--tags <tags>`   | option   | No       | Comma-separated tags                 | -       |
| `--public`        | option   | No       | Make resource publicly accessible    | `false` |

**Examples:**

```bash
# Create a basic resource
command create item my-item

# Create with description and tags
command create item my-item --description "Sample item" --tags "tag1,tag2"
```

### `list`

Display a list of resources.

**Usage:**

```bash
command list [resource-type] [options]
```

**Options:**

| Option                  | Description                        | Default |
|-------------------------|------------------------------------|---------|
| `--filter <expression>` | Filter results by criteria         | -       |
| `--sort <field>`        | Sort by field (`name`, `date`)     | `name`  |
| `--limit <number>`      | Maximum number of results          | `50`    |
| `--all, -a`             | Show all items (including archived)| `false` |

**Examples:**

```bash
# List all resources
command list

# List with filters
command list --filter "status=active" --sort date

# List all including archived
command list --all
```

### `update`

Update an existing resource.

**Usage:**

```bash
command update <resource-id> [options]
```

**Parameters:**

| Parameter         | Type     | Required | Description                  |
|-------------------|----------|----------|------------------------------|
| `resource-id`     | argument | Yes      | ID of resource to update     |
| `--name <name>`   | option   | No       | Update resource name         |
| `--description <text>` | option | No  | Update description           |
| `--tags <tags>`   | option   | No       | Update tags (overwrites all) |
| `--add-tag <tag>` | option   | No       | Add a single tag             |
| `--remove-tag <tag>` | option | No    | Remove a single tag          |

**Examples:**

```bash
# Update name
command update 123 --name "New Name"

# Add tags
command update 123 --add-tag production --add-tag critical
```

### `delete`

Delete one or more resources.

**Usage:**

```bash
command delete <resource-id>... [options]
```

**Parameters:**

| Parameter         | Type     | Required | Description                        | Default |
|-------------------|----------|----------|------------------------------------|---------|
| `resource-id`     | argument | Yes      | One or more resource IDs to delete | -       |
| `--force, -f`     | option   | No       | Skip confirmation prompt           | `false` |
| `--recursive, -r` | option   | No       | Delete related resources           | `false` |

**Examples:**

```bash
# Delete single resource (with confirmation)
command delete 123

# Delete multiple resources without confirmation
command delete 123 456 789 --force

# Delete with related resources
command delete 123 --recursive
```

### `config`

Manage configuration settings.

**Usage:**

```bash
command config <action> [options]
```

**Subcommands:**

#### `config get`

Retrieve configuration value(s).

```bash
command config get [key]
```

#### `config set`

Set configuration value.

```bash
command config set <key> <value>
```

#### `config list`

List all configuration settings.

```bash
command config list
```

#### `config reset`

Reset configuration to defaults.

```bash
command config reset [--confirm]
```

**Examples:**

```bash
# Get specific value
command config get api.endpoint

# Set a value
command config set api.timeout 30

# View all settings
command config list

# Reset to defaults
command config reset --confirm
```

## Environment Variables

| Variable           | Description                      | Default         |
|--------------------|----------------------------------|-----------------|
| `COMMAND_API_KEY`  | API authentication key           | -               |
| `COMMAND_ENDPOINT` | API endpoint URL                 | `https://api.example.com` |
| `COMMAND_TIMEOUT`  | Request timeout in seconds       | `30`            |
| `COMMAND_LOG_LEVEL`| Logging level (`debug`, `info`, `error`) | `info` |

## Exit Codes

| Code | Description                          |
|------|--------------------------------------|
| 0    | Success                              |
| 1    | General error                        |
| 2    | Invalid arguments or options         |
| 3    | Resource not found                   |
| 4    | Permission denied                    |
| 130  | Command interrupted (Ctrl+C)         |

:::tip Shell Completion
Enable shell completion for better command-line experience:

```bash
# Bash
command completion bash > /etc/bash_completion.d/command

# Zsh
command completion zsh > ~/.zsh/completion/_command
```
:::