> ## 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.

# Tracing

> CLI commands for trace initialization, applying decorators, removing instrumentation, and refreshing suggestions.

All trace commands live under the `trace` group (alias: `t`).

```bash theme={"system"}
valiqor trace <init|apply|uninstrument|refresh>
# or
valiqor t <init|apply|uninstrument|refresh>
```

***

## trace init

Scan your codebase for LLM usage and generate a `valiqor_init.py` initialization file with workflow suggestions.

```bash theme={"system"}
valiqor trace init [flags]
```

| Flag                | Type   | Default | Description                                     |
| ------------------- | ------ | ------- | ----------------------------------------------- |
| `--defaults` / `-d` | `flag` | `false` | Use default settings without prompting          |
| `--force` / `-f`    | `flag` | `false` | Overwrite existing `valiqor_init.py`            |
| `--no-scan`         | `flag` | `false` | Skip codebase scanning (faster, no suggestions) |
| `--verbose` / `-v`  | `flag` | `false` | Show detailed scan output                       |

### What It Does

1. Runs a context scanner for feature detection
2. Scans your codebase for LLM usage (detects providers and entry points)
3. Generates `valiqor_init.py` with recommended workflow decorators
4. Creates the trace output directory
5. Updates `.gitignore` to exclude trace files

### Example

```bash theme={"system"}
# Interactive initialization
valiqor trace init

# Quick setup with defaults, overwriting existing config
valiqor trace init --defaults --force
```

If no `.valiqorrc` exists, the CLI auto-configures the project before scanning.

***

## trace apply

Apply `@trace_workflow` decorators to your Python files based on scan suggestions.

```bash theme={"system"}
valiqor trace apply [flags]
```

| Flag               | Type   | Default | Description                                       |
| ------------------ | ------ | ------- | ------------------------------------------------- |
| `--dry-run`        | `flag` | `false` | Preview changes without modifying files           |
| `--all`            | `flag` | `false` | Apply to all entry points, including alternatives |
| `--first`          | `flag` | `false` | Apply to the first suggestion per file only       |
| `--verbose` / `-v` | `flag` | `false` | Show detailed output                              |

### Behavior

* By default, applies decorators only to **recommended** entry points.
* `--all` includes alternative entry points as well.
* Creates backups of modified files before applying changes.
* If `valiqor_init.py` is stale (scan ID mismatch), the CLI re-scans automatically before applying.

### Example

```bash theme={"system"}
# Preview what decorators would be applied
valiqor trace apply --dry-run

# Apply to recommended entry points
valiqor trace apply

# Apply to every detected entry point
valiqor trace apply --all
```

***

## trace uninstrument

Remove auto-applied Valiqor instrumentation (decorators and imports) from Python files.

```bash theme={"system"}
valiqor trace uninstrument [files...] [flags]
```

| Flag             | Type         | Default          | Description                                             |
| ---------------- | ------------ | ---------------- | ------------------------------------------------------- |
| `files`          | `positional` | all `*.py` files | Specific files to uninstrument                          |
| `--dry-run`      | `flag`       | `false`          | Show what would be removed without making changes       |
| `--no-recursive` | `flag`       | `false`          | Only process the current directory (default: recursive) |

### Example

```bash theme={"system"}
# Remove instrumentation from all Python files (recursive)
valiqor trace uninstrument

# Preview removal for specific files
valiqor trace uninstrument app.py utils.py --dry-run

# Process current directory only (no recursion)
valiqor trace uninstrument --no-recursive
```

<Info>
  Excludes dotfiles and `valiqor_init.py` by default.
</Info>

***

## trace refresh

Re-scan the codebase and regenerate `valiqor_init.py` with updated suggestions.

```bash theme={"system"}
valiqor trace refresh [flags]
```

| Flag               | Type   | Default | Description               |
| ------------------ | ------ | ------- | ------------------------- |
| `--verbose` / `-v` | `flag` | `false` | Show detailed scan output |

### Example

```bash theme={"system"}
valiqor trace refresh
```

Runs the context scanner and LLM detection again, then prompts before overwriting the existing `valiqor_init.py`.