> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valiqor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Overview

> Install the Valiqor CLI, understand global options, and learn the command structure.

## Installation

The CLI is included with the Valiqor Python SDK. Install it with pip:

```bash theme={"system"}
pip install valiqor
```

After installation the `valiqor` command is available system-wide.

```bash theme={"system"}
valiqor --version
```

<Tip>
  `--version` also lists which optional modules are installed (Trace, Scanner, Eval, Security, Failure Analysis).
</Tip>

***

## Command Structure

```text theme={"system"}
valiqor <command> [subcommand] [flags]
```

| Command Group                                | Description                                         |
| -------------------------------------------- | --------------------------------------------------- |
| [`login`](/cli/authentication#login)         | Authenticate via browser or credentials             |
| [`signup`](/cli/authentication#signup)       | Create a new account                                |
| [`logout`](/cli/authentication#logout)       | Clear stored credentials                            |
| [`verify`](/cli/authentication#verify-email) | Verify your email address                           |
| [`keys`](/cli/authentication#keys)           | Create, list, or delete API keys                    |
| [`config`](/cli/configuration#config)        | Interactive setup, show, or update project settings |
| [`status`](/cli/configuration#status)        | Show auth, config, and connection status            |
| [`test`](/cli/configuration#test)            | Validate configuration and connectivity             |
| [`upload`](/cli/configuration#upload)        | Upload trace and scan files                         |
| [`trace`](/cli/tracing)                      | Initialize, apply, remove, and refresh tracing      |
| [`scan`](/cli/scanning)                      | Run AST-based code scans                            |
| [`eval`](/cli/evaluation)                    | Run evaluations and inspect results                 |
| [`security`](/cli/security)                  | Security audits and red-team simulations            |
| [`fa`](/cli/failure-analysis)                | Failure analysis on traces and datasets             |

***

## Global Options

Every command supports:

| Flag               | Description                               |
| ------------------ | ----------------------------------------- |
| `--help` / `-h`    | Show help for any command or subcommand   |
| `--version` / `-v` | Print SDK version and module availability |

***

## Credential Storage

The CLI stores credentials in two locations:

| Location   | Purpose                    | File                             |
| ---------- | -------------------------- | -------------------------------- |
| **Global** | Shared across all projects | `~/.valiqor/credentials.json`    |
| **Local**  | Per-project override       | `.valiqorrc` in the project root |

Credential resolution order:

1. CLI flag (`--api-key`)
2. Local `.valiqorrc`
3. Global `~/.valiqor/credentials.json`
4. Environment variable `VALIQOR_API_KEY`

***

## Configuration File

Project settings are stored in `.valiqorrc` (JSON) at the project root.

```json theme={"system"}
{
  "project_name": "my-app",
  "api_key": "vq-...",
  "trace_dir": "valiqor_output/traces",
  "scan_dir": "valiqor_output/scans",
  "environment": "development",
  "valiqor_intelligence": true,
  "debug": false
}
```

See [Configuration](/cli/configuration) for details on every key.

***

## Module Availability

Some commands require optional SDK modules. The CLI checks availability at runtime and provides install hints when a module is missing.

| Module                     | Required For        |
| -------------------------- | ------------------- |
| `valiqor.trace`            | `trace` commands    |
| `valiqor.scanner`          | `scan` commands     |
| `valiqor.eval`             | `eval` commands     |
| `valiqor.security`         | `security` commands |
| `valiqor.failure_analysis` | `fa` commands       |

Run `valiqor --version` to see which modules are installed.

***

## Quick Start

```bash theme={"system"}
# 1. Sign up or log in
valiqor signup
valiqor login

# 2. Initialize a project
valiqor config

# 3. Verify everything works
valiqor test

# 4. Run your first evaluation
valiqor eval run --dataset data.json --metrics factual_accuracy,coherence
```