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

# Configuration & Setup

> Configure the CLI, manage environments, check for updates, and troubleshoot issues

<Note>
  **Early Access** - The Dcycle CLI is currently available for enterprise customers.
  [Contact us](/docs/support) to learn more about access.
</Note>

## Version & Updates

### Check Version

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy version
```

Output:

```
Version
  Binary:   dcy
  Version:  0.0.44
  Commit:   abc1234
  Date:     2024-06-15
  Go:       go1.24.3
  Platform: darwin/arm64
```

### Check for Updates

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy version --check
```

If an update is available:

```
Update available: 0.0.43 → 0.0.44
  brew upgrade dcy
  https://github.com/Dcycle-by-WUM/dcy-releases/releases/tag/v0.0.44
```

### Update

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
brew update && brew upgrade dcy
```

### JSON Output

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Machine-readable version info
dcy version --format json

# Machine-readable update check
dcy version --check --format json
```

***

## Configuration

The CLI stores configuration in a YAML file. View the file location with:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy config path
# ~/.config/dcy/config.yaml
```

### View Configuration

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Full config (credentials redacted)
dcy config show

# Key-value summary
dcy config list
```

Output of `config list`:

```
Host: https://api.dcycle.io
Environment: production
User: jane@company.com
Organization: Acme Corp
Organization ID: abc123-def456-...
Token: ***
```

### Get / Set Values

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Read a single value
dcy config get host
dcy config get organization_id

# Set a value (validates the input)
dcy config set host https://api.dcycle.io
dcy config set host staging          # resolves alias → https://api.stg.dcycle.io
dcy config set organization_id 550e8400-e29b-41d4-a716-446655440000
```

`config set` validates values before saving:

* **host** must be a URL (`http://` or `https://`) or a known alias (`production`, `staging`, `dev`, `local`)
* **organization\_id** must be a valid UUID

### Clear a Value

Remove a single config value without resetting everything:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy config unset organization_id
# unset organization_id (was 550e8400-e29b-41d4-a716-446655440000)

dcy config unset host
# unset host (was https://api.dcycle.io)

dcy config unset token
# unset token (was ***)
```

Sensitive values (token, api\_key) are redacted in the confirmation output.

<Tip>
  Use `config unset` when you need to clear a single value.
  Use `config reset` when you want to start fresh.
</Tip>

### Reset Configuration

Remove all stored credentials and settings:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy config reset

# Skip confirmation
dcy config reset --yes   # or: dcy config reset -y
```

<Warning>
  This removes your authentication token, API key, and organization settings. You will need to log in again.
</Warning>

### Import from Legacy CLI

If you previously used the Python-based `dc` CLI, import your existing settings:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy config import-legacy

# Overwrite existing v2 config
dcy config import-legacy --force
```

***

## Environment Management

The CLI supports multiple environments. Switch between them with `config host`:

### List Environments

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy config host list
```

Output:

```
production  https://api.dcycle.io           PROD     yes
staging     https://api.stg.dcycle.io       STAGING
dev         https://api.dev.dcycle.io       DEV
local       http://localhost:8000           LOCAL
```

### Switch Environment

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# By alias
dcy config host set production
dcy config host set staging
dcy config host set dev
dcy config host set local

# By URL
dcy config host set https://api.dcycle.io
```

<Tip>
  After switching environments, you need to authenticate again for the new host:
  `dcy auth login` or set `DCYCLE_API_KEY`.
</Tip>

### Environment Variables

Override config values without modifying the config file. Useful for CI/CD pipelines:

| Variable         | Description                  | Example                 |
| ---------------- | ---------------------------- | ----------------------- |
| `DCYCLE_API_KEY` | API key (skips OAuth login)  | `sk-abc123...`          |
| `DCYCLE_HOST`    | Override API host URL        | `https://api.dcycle.io` |
| `DCYCLE_ORG_ID`  | Override active organization | `abc123-def456`         |
| `DCYCLE_FORMAT`  | Default output format        | `json`                  |
| `DCYCLE_VERBOSE` | Enable HTTP logging          | `1` or `true`           |
| `DCYCLE_TIMEOUT` | HTTP timeout (seconds)       | `60`                    |
| `NO_COLOR`       | Disable ANSI colors          | `1`                     |

Command-line flags always take precedence over environment variables.

Use `dcy config list` to see which environment variables are currently active:

```
Configuration
  Host:            https://api.dcycle.io
  Environment:     production
  ...
⚠ env override: DCYCLE_API_KEY=*** → api_key
⚠ env override: DCYCLE_FORMAT=json → format
```

### Automatic Retry

The CLI automatically retries failed requests caused by transient server issues:

| Status Code   | Meaning                | Retried                             |
| ------------- | ---------------------- | ----------------------------------- |
| `429`         | Rate limited           | Yes — respects `Retry-After` header |
| `502`         | Bad gateway            | Yes                                 |
| `503`         | Service unavailable    | Yes                                 |
| `504`         | Gateway timeout        | Yes                                 |
| `4xx` / `500` | Client or server error | No                                  |

Retry behavior:

* **Up to 3 retries** with exponential backoff (1s, 2s, 4s)
* **Transient connection errors** (DNS, dial failures) are retried — but timeouts are not
* Retry attempts are logged to stderr when `--verbose` is enabled

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# See retry attempts in real time
dcy facility list --verbose
# >> GET https://api.dcycle.io/v1/facilities [auth=api-key]
# << 503 Service Unavailable (142ms)
# >> retry 1/3 after 1s
# << 200 OK (89ms)
```

<Note>
  Since retries are built-in, you don't need to wrap `dcy` commands in shell retry loops for transient failures. Shell-level retry is only useful for restarting after non-retryable errors like timeouts.
</Note>

***

## Health Check

Run `dcy doctor` to verify your CLI setup is working correctly:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy doctor
```

Output:

```
CLI Health Check

  ✓ Config file — /home/jane/.config/dcy/config.yaml
  ✓ API host — https://api.dcycle.io (production)
  ✓ Authentication — API key
  ✓ Organization — Acme Corp (abc123-def456)
  ✓ API connectivity — authenticated as jane@company.com
  ✓ Version — 0.0.44 (latest)

All checks passed.
```

When environment variables override config file values, doctor reports them:

```
CLI Health Check

  ✓ Config file — /home/jane/.config/dcy/config.yaml
  ✓ API host — https://api.stg.dcycle.io (staging)
  ✓ Authentication — API key
  ✓ Organization — Acme Corp (abc123-def456)
  ✓ Env override — DCYCLE_HOST=https://api.stg.dcycle.io → host
  ✓ Env override — DCYCLE_API_KEY=*** → api_key
  ✓ API connectivity — authenticated as jane@company.com
  ✓ Version — 0.0.44 (latest)

All checks passed.
```

### What it checks

| Check            | Pass                       | Warn             | Fail                     |
| ---------------- | -------------------------- | ---------------- | ------------------------ |
| Config file      | File exists                | —                | Missing or unreadable    |
| API host         | Set and valid              | —                | Not configured           |
| Authentication   | Token or API key present   | —                | Not authenticated        |
| Organization     | Set                        | Not set          | —                        |
| Env override     | Shows each active override | —                | —                        |
| API connectivity | API responds, shows email  | —                | Connection or auth error |
| Version          | Up to date                 | Update available | —                        |

### JSON Output

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy doctor --json
```

Returns an array of check objects:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  {"name": "Config file", "status": "ok", "detail": "/home/jane/.config/dcy/config.yaml"},
  {"name": "API host", "status": "ok", "detail": "https://api.dcycle.io (production)"},
  {"name": "Authentication", "status": "ok", "detail": "API key"},
  {"name": "Organization", "status": "ok", "detail": "Acme Corp (abc123-def456)"},
  {"name": "API connectivity", "status": "ok", "detail": "authenticated as jane@company.com"},
  {"name": "Version", "status": "ok", "detail": "0.0.44 (latest)"}
]
```

<Tip>
  `dcy doctor` returns exit code 1 when any check fails or warns, so you can gate scripts on it:
  `dcy doctor && dcy facility list`
</Tip>

<Tip>
  Use `dcy doctor --json | jq '.[] | select(.status != "ok")'` to quickly find issues.
</Tip>

***

## Shell Completions

Enable tab completion for commands, flags, and values.

### Bash

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Load for current session
source <(dcy completion bash)

# Load permanently (Linux)
dcy completion bash > /etc/bash_completion.d/dcy

# Load permanently (macOS with Homebrew)
dcy completion bash > $(brew --prefix)/etc/bash_completion.d/dcy
```

### Zsh

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Enable completion (if not already)
echo "autoload -U compinit; compinit" >> ~/.zshrc

# Load permanently
dcy completion zsh > "${fpath[1]}/_dcy"
```

### Fish

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Load for current session
dcy completion fish | source

# Load permanently
dcy completion fish > ~/.config/fish/completions/dcy.fish
```

### PowerShell

```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Load for current session
dcy completion powershell | Out-String | Invoke-Expression

# Load permanently — add the output to your PowerShell profile
```

<Tip>
  Completions include context-aware values — `--status` suggests valid status values, `--type` suggests valid types, and `--format` suggests `text` or `json`.
</Tip>

***

## Troubleshooting

### Error Format

When a command fails, the CLI prints an error message and a recovery hint:

```
Error: session expired or invalid
Hint: run `dcy auth login` or set DCYCLE_API_KEY
```

The hint suggests the most likely recovery action based on the error type.

With `--json` (or `--format json`), errors are output as structured JSON to stderr:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"error":"session expired or invalid","type":"authentication","hint":"run `dcy auth login` or set DCYCLE_API_KEY","exit_code":2}
```

| Field       | Description                                                                                                                                  |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `error`     | Error message (always present)                                                                                                               |
| `type`      | Error category: `authentication`, `permission`, `connection`, `configuration`, `not_found`, `validation`, `api` (omitted for generic errors) |
| `hint`      | Recovery suggestion (omitted when not applicable)                                                                                            |
| `exit_code` | Process exit code (matches the exit code table below)                                                                                        |

This lets scripts parse errors consistently:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
error=$(dcy facility list --json 2>&1 1>/dev/null)
if [ $? -ne 0 ]; then
  echo "$error" | jq -r '.hint // .error'
fi
```

### Token Expired

```
Error: session expired or invalid
Hint: run `dcy auth login` or set DCYCLE_API_KEY
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Check current auth status
dcy auth status

# Re-authenticate
dcy auth login
```

### Wrong Organization

```
Error: access denied: forbidden
Hint: check your organization with `dcy org list` or switch with `dcy org set <org-id>`
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Check current org
dcy config list

# List available orgs
dcy org list

# Switch org
dcy org set <org-id>
```

### Missing Configuration

```
Error: no organization set
Hint: run `dcy doctor` for a full setup check
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Run a full health check
dcy doctor

# Review your config
dcy config show
```

### Connection Issues

```
Error: cannot connect to https://api.dcycle.io
Hint: check your network connection or run `dcy doctor`
```

For timeouts, the hint suggests increasing the timeout:

```
Error: request timed out after 30s
Hint: increase timeout with --timeout or DCYCLE_TIMEOUT
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Full diagnostic
dcy doctor

# Debug a specific request
dcy vehicle list --verbose

# Increase timeout for slow requests
dcy purchase list --timeout 120
```

The `--verbose` flag shows the full HTTP request and response on stderr, which helps diagnose API issues without interfering with JSON output.

### Exit Codes

The CLI returns typed exit codes so scripts can distinguish between error categories:

| Code  | Meaning                     | Hint                                      |
| ----- | --------------------------- | ----------------------------------------- |
| `0`   | Success                     | —                                         |
| `1`   | General error               | —                                         |
| `2`   | Authentication / permission | `dcy auth login` or `dcy org set`         |
| `3`   | Connection / timeout        | `dcy doctor` or `--timeout`               |
| `4`   | Not found                   | Check resource ID or run the list command |
| `5`   | Validation                  | Check input values                        |
| `130` | Interrupted (Ctrl+C)        | —                                         |
| `143` | Terminated (SIGTERM)        | —                                         |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy facility list --json > facilities.json
case $? in
  0) echo "OK" ;;
  2) echo "Re-auth needed"; dcy auth login ;;
  3) echo "API unreachable"; dcy doctor ;;
  4) echo "Resource not found" ;;
  130) echo "Cancelled" ;;
  143) echo "Terminated" ;;
  *) echo "Failed" ;;
esac
```

### Reset Everything

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy config reset --yes
dcy auth login
dcy org set <org-id>
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/cli/authentication">
    Set up OAuth login or API key authentication
  </Card>

  <Card title="Organizations" icon="sitemap" href="/cli/organizations">
    Manage organizations and members
  </Card>
</CardGroup>