# CLI Reference

This document provides a comprehensive reference for the DeepLint command-line interface (CLI), including all available commands, options, and usage examples.

## Command Structure

DeepLint commands follow this general structure:

```bash
deeplint [command] [options]
```

If no command is specified, DeepLint runs the default command, which analyzes staged changes in the current Git repository.

## Global Options

These options can be used with any command:

| Option            | Description                   | Default | Example                              |
| ----------------- | ----------------------------- | ------- | ------------------------------------ |
| `--help`, `-h`    | Show help information         | -       | `deeplint --help`                    |
| `--version`, `-v` | Show version information      | -       | `deeplint --version`                 |
| `--debug`         | Enable debug output           | `false` | `deeplint --debug`                   |
| `--verbose`       | Enable verbose output         | `false` | `deeplint --verbose`                 |
| `--config`        | Specify a custom config file  | -       | `deeplint --config=custom.config.js` |
| `--json`          | Output results in JSON format | `false` | `deeplint --json`                    |

## Commands

### Default Command

The default command runs when no command is specified. It analyzes staged changes in the current Git repository.

```bash
deeplint [options]
```

#### Options

| Option           | Description                      | Default | Example                                              |
| ---------------- | -------------------------------- | ------- | ---------------------------------------------------- |
| `--context`      | Context depth (light or deep)    | `light` | `deeplint --context=deep`                            |
| `--unstaged`     | Include unstaged changes         | `false` | `deeplint --unstaged`                                |
| `--dump`         | Dump context to a file           | -       | `deeplint --dump=context.json`                       |
| `--instructions` | Custom instructions for analysis | -       | `deeplint --instructions="Focus on security issues"` |

#### Examples

```bash
# Analyze staged changes with default options
deeplint

# Analyze unstaged changes with deep context
deeplint --unstaged --context=deep

# Analyze staged changes and dump context to a file
deeplint --dump=context.json

# Analyze staged changes with custom instructions
deeplint --instructions="Check for memory leaks"
```

### Init Command

The `init` command initializes DeepLint in a repository, creating a configuration file.

```bash
deeplint init [options]
```

#### Options

| Option          | Description                             | Default | Example                 |
| --------------- | --------------------------------------- | ------- | ----------------------- |
| `--force`, `-f` | Overwrite existing configuration        | `false` | `deeplint init --force` |
| `--yaml`        | Use YAML format for configuration       | `false` | `deeplint init --yaml`  |
| `--js`          | Use JavaScript format for configuration | `true`  | `deeplint init --js`    |

#### Examples

```bash
# Initialize DeepLint with JavaScript configuration
deeplint init

# Initialize DeepLint with YAML configuration
deeplint init --yaml

# Force overwrite of existing configuration
deeplint init --force
```

### Help Command

The `help` command displays help information for DeepLint or a specific command.

```bash
deeplint help [command]
```

#### Examples

```bash
# Show general help
deeplint help

# Show help for the init command
deeplint help init
```

### Check Command

The `check` command analyzes your codebase using LLM-powered analysis, providing advanced linting, code review, and suggestions using AI.

```bash
deeplint check [options] [files...]
```

* If no files are specified, DeepLint analyzes staged changes by default.
* You can specify files or directories to analyze specific targets.

#### Options

| Option           | Description                                    | Default / Source                         |
| ---------------- | ---------------------------------------------- | ---------------------------------------- |
| `--provider`     | LLM provider to use                            | `"openai"`                               |
| `--model`        | LLM model to use                               | `process.env.OPENAI_MODEL` or `"gpt-4o"` |
| `--api-key`      | API key for the LLM provider                   | `process.env.OPENAI_API_KEY`             |
| `--instructions` | Additional instructions for the LLM            | none                                     |
| `--json`         | Output results in JSON format                  | `false`                                  |
| `--context`      | Context depth for analysis (`light` or `deep`) | `"light"`                                |
| `--unstaged`     | Include unstaged changes in the analysis       | `false`                                  |
| `--debug`        | Enable debug output                            | `false`                                  |
| `--verbose`      | Enable verbose output                          | `false`                                  |

#### Examples

```bash
# Analyze staged changes with LLM-powered analysis
deeplint check

# Analyze with a custom model
deeplint check --model=gpt-4

# Add custom instructions
deeplint check --instructions="Focus on security issues."

# Output as JSON
deeplint check --json

# Analyze unstaged changes
deeplint check --unstaged

# Analyze specific files
deeplint check src/llm/ src/commands/check-command.ts
```

## Planned Commands

The following commands are planned for future releases:

### Config Command (Planned)

The `config` command will allow viewing and modifying configuration values.

```bash
deeplint config [action] [key] [value] [options]
```

#### Actions (Planned)

* `get`: Get a configuration value
* `set`: Set a configuration value
* `list`: List all configuration values

#### Examples (Planned)

```bash
# Get a configuration value
deeplint config get contextBuilder.maxTokens

# Set a configuration value
deeplint config set contextBuilder.maxTokens 16000

# List all configuration values
deeplint config list
```

## Environment Variables

DeepLint supports the following environment variables:

| Variable               | Description                        | Example                                   |
| ---------------------- | ---------------------------------- | ----------------------------------------- |
| `DEEPLINT_CONFIG_PATH` | Path to the configuration file     | `DEEPLINT_CONFIG_PATH=/path/to/config.js` |
| `DEEPLINT_DEBUG`       | Enable debug output                | `DEEPLINT_DEBUG=true`                     |
| `DEEPLINT_VERBOSE`     | Enable verbose output              | `DEEPLINT_VERBOSE=true`                   |
| `OPENAI_API_KEY`       | OpenAI API key for LLM integration | `OPENAI_API_KEY=sk-...`                   |
| `OPENAI_MODEL`         | Default model for OpenAI           | `OPENAI_MODEL=gpt-4o`                     |

## Exit Codes

DeepLint uses the following exit codes:

| Code | Description                                |
| ---- | ------------------------------------------ |
| 0    | Success - No issues found                  |
| 1    | Error - Command failed to execute          |
| 2    | Issues - Issues were found during analysis |

## Configuration

DeepLint can be configured using a configuration file. By default, DeepLint looks for the following files in the current directory:

* `deeplint.config.js`
* `.deeplintrc.js`
* `.deeplintrc.json`
* `.deeplintrc.yml`
* `.deeplintrc.yaml`

You can also specify a custom configuration file using the `--config` option.

LLM options can be set via CLI flags, environment variables, or config file. Precedence is:

1. CLI arguments
2. Environment variables
3. Config file (`llm` section)
4. Built-in defaults

For more information about LLM configuration, see the [Configuration Guide](https://docs.deeplint.com/getting-started/configuration).\
For general configuration, see the [Configuration Reference](https://docs.deeplint.com/configuration-reference/configuration).

## Examples

### Basic Usage

```bash
# Initialize DeepLint in a repository
deeplint init

# Analyze staged changes
git add .
deeplint

# Analyze unstaged changes
deeplint --unstaged
```

### Advanced Usage

```bash
# Analyze staged changes with deep context and custom instructions
deeplint --context=deep --instructions="Focus on performance issues"

# Analyze staged changes and output results in JSON format
deeplint --json > results.json

# Initialize DeepLint with YAML configuration and force overwrite
deeplint init --yaml --force
```

## Troubleshooting

### Common Issues

#### No Staged Changes

If you run DeepLint without any staged changes, you'll see an error message:

```
ERROR: No staged changes found. Stage changes with 'git add' or use --unstaged to analyze unstaged changes.
```

To fix this, either:

1. Stage some changes with `git add`, or
2. Use the `--unstaged` flag to analyze unstaged changes:

```bash
deeplint --unstaged
```

#### Not a Git Repository

If you run DeepLint outside of a Git repository, you'll see an error message:

```
ERROR: Not a Git repository. Initialize a Git repository with 'git init' or navigate to a Git repository.
```

To fix this, either:

1. Navigate to a Git repository, or
2. Initialize a Git repository in your current directory:

```bash
git init
```

#### Configuration Not Found

If DeepLint can't find a configuration file, it will use default values. To create a configuration file:

```bash
deeplint init
```

## Related Documentation

* [Getting Started](https://docs.deeplint.com/getting-started/installation)
* [Configuration Reference](https://docs.deeplint.com/configuration-reference/configuration)
* [Command System](https://github.com/deeplint-dev/deeplint-cli/blob/main/docs/developer/core-concepts/command-system.md)