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

# Steering Commands

> Configure runtime model routing rules and fallback behaviors

## Overview

Steering commands manage runtime routing rules that automatically adjust model selection based on intent, user, time of day, and other conditions. Steering rules complement the Cortex Router by providing static, deterministic routing policies.

## Commands

### list

Display all active steering rules.

```bash theme={null}
switchAILocal steering list
```

**Output:**

```
Active Steering Rules:

ID              INTENT          MODEL              PRIORITY  CONDITIONS
--              ------          -----              --------  ----------
fallback-1      coding          ollama:codellama   100       provider:geminicli unhealthy
secure-route    *               ollama:llama3.2    200       user:enterprise-*
off-hours       fast            switchai-fast      150       hour:22-06
```

<Info>
  Steering rules are loaded from `~/.switchailocal/steering/*.yaml` files.
</Info>

### test

Test a steering rule against specific conditions.

```bash theme={null}
switchAILocal steering test [options]
```

<ParamField path="--file" type="string">
  Path to specific rule file to test
</ParamField>

<ParamField path="--intent" type="string">
  Intent to test against (e.g., `coding`, `reasoning`, `fast`)
</ParamField>

<ParamField path="--user" type="string">
  User API key hash to test against
</ParamField>

<ParamField path="--hour" type="integer">
  Hour of day to test (0-23, default: current hour)
</ParamField>

<ParamField path="--format" type="string">
  Output format: `table` or `json` (default: `table`)
</ParamField>

**Example:**

```bash theme={null}
switchAILocal steering test --intent coding --hour 23
```

**Output:**

```
Testing steering rules:

Intent: coding
Hour: 23

Matching Rules:
  - off-hours: switchai-fast (priority: 150)
  - fallback-1: ollama:codellama (priority: 100)

Selected Model: switchai-fast
Reason: Highest priority match
```

### validate

Validate steering rule syntax and conditions.

```bash theme={null}
switchAILocal steering validate [--file <path>]
```

**Example:**

```bash theme={null}
switchAILocal steering validate --file ~/.switchailocal/steering/custom.yaml
```

**Output:**

```
Validating: /Users/user/.switchailocal/steering/custom.yaml

✓ Syntax valid
✓ All conditions recognized
✓ Model references valid
✓ Priority values acceptable

Validation passed.
```

### reload

Reload all steering rules from disk without restarting the server.

```bash theme={null}
switchAILocal steering reload
```

**Output:**

```
Reloading steering rules...

✓ Loaded 5 rules from 3 files
✓ All rules validated successfully

Steering engine reloaded.
```

<Warning>
  Hot reload is only available when the server is running with `--enable-steering`.
</Warning>

## Steering Rule Format

Steering rules are defined in YAML files:

```yaml ~/.switchailocal/steering/custom-routing.yaml theme={null}
rules:
  - id: coding-local
    intent: coding
    model: ollama:codellama
    priority: 100
    conditions:
      - provider: geminicli
        status: unhealthy
      - provider: claudecli
        status: unhealthy
  
  - id: secure-data
    intent: "*"
    model: ollama:llama3.2
    priority: 200
    conditions:
      - user_pattern: "enterprise-*"
      - pii_detected: true
  
  - id: off-hours-fast
    intent: fast
    model: switchai-fast
    priority: 150
    conditions:
      - hour_range: "22-06"
```

### Rule Fields

<ParamField path="id" type="string" required>
  Unique identifier for the rule
</ParamField>

<ParamField path="intent" type="string" required>
  Target intent (`coding`, `reasoning`, `fast`, `secure`, or `*` for all)
</ParamField>

<ParamField path="model" type="string" required>
  Model to route to (supports provider prefixes)
</ParamField>

<ParamField path="priority" type="integer" required>
  Priority (0-1000, higher = preferred)
</ParamField>

<ParamField path="conditions" type="array">
  List of conditions that must all be true for the rule to apply
</ParamField>

### Supported Conditions

* `provider: <name>` + `status: <healthy|unhealthy|degraded>`
* `user_pattern: <glob>` - Match user API key hash
* `hour_range: <start-end>` - Match hour of day (24h format)
* `pii_detected: <true|false>` - Match PII detection result
* `quota_remaining: <percentage>` - Match quota threshold

## Use Cases

<Accordion title="Automatic Failover to Local Models">
  Route to local models when cloud providers are unhealthy:

  ```yaml theme={null}
  - id: cloud-failover
    intent: "*"
    model: ollama:llama3.2
    priority: 90
    conditions:
      - provider: geminicli
        status: unhealthy
      - provider: claudecli
        status: unhealthy
  ```
</Accordion>

<Accordion title="Sensitive Data Routing">
  Force local models for requests containing PII:

  ```yaml theme={null}
  - id: pii-local
    intent: "*"
    model: ollama:llama3.2
    priority: 200
    conditions:
      - pii_detected: true
  ```
</Accordion>

<Accordion title="Off-Hours Cost Optimization">
  Use faster, cheaper models during off-peak hours:

  ```yaml theme={null}
  - id: night-fast
    intent: fast
    model: switchai-fast
    priority: 150
    conditions:
      - hour_range: "22-06"
  ```
</Accordion>

<Accordion title="Enterprise User Isolation">
  Route enterprise users to dedicated models:

  ```yaml theme={null}
  - id: enterprise-dedicated
    intent: "*"
    model: ollama:llama3.2
    priority: 180
    conditions:
      - user_pattern: "enterprise-*"
  ```
</Accordion>

## Integration with Cortex Router

Steering rules and Cortex Router work together:

1. **Cortex Router** classifies the request intent
2. **Steering rules** are evaluated against the classified intent
3. If a steering rule matches, its model overrides the Cortex selection
4. If no steering rule matches, Cortex selection is used

<Tip>
  Use steering for **deterministic, policy-based routing** and Cortex for **intelligent, adaptive routing**.
</Tip>

## Troubleshooting

<Accordion title="Rules not applying">
  * Verify rule files are in `~/.switchailocal/steering/`
  * Check file permissions (must be readable)
  * Run `steering validate` to check syntax
  * Ensure server was started with `--enable-steering`
</Accordion>

<Accordion title="Multiple rules matching">
  * Higher priority rules take precedence
  * If priorities are equal, first defined rule wins
  * Use `steering test` to debug rule evaluation
</Accordion>

<Accordion title="Condition not recognized">
  * Check condition syntax against supported conditions
  * Ensure provider names match configured providers
  * Verify hour ranges are in 24h format (0-23)
</Accordion>

## See Also

* [Cortex Router](/intelligent-systems/cortex-router) - Intelligent routing system
* [Heartbeat Commands](/cli/heartbeat) - Monitor provider health
* [Hooks Commands](/cli/hooks) - Set up event triggers