Configuration & Setup

Early Access - The Dcycle CLI is currently available for enterprise customers. Contact us to learn more about access.

Version & Updates

Check Version

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

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

brew update && brew upgrade dcy

JSON Output

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

dcy config path
# ~/.config/dcy/config.yaml

View Configuration

# 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

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

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.

Use config unset when you need to clear a single value. Use config reset when you want to start fresh.

Reset Configuration

Remove all stored credentials and settings:

dcy config reset

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

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

Import from Legacy CLI

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

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

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

# 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

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

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

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

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.

Health Check

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

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

dcy doctor --json

Returns an array of check objects:

[
  {"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)"}
]

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

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

Shell Completions

Enable tab completion for commands, flags, and values.

Bash

# 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

# Enable completion (if not already)
echo "autoload -U compinit; compinit" >> ~/.zshrc

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

Fish

# Load for current session
dcy completion fish | source

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

PowerShell

# Load for current session
dcy completion powershell | Out-String | Invoke-Expression

# Load permanently — add the output to your PowerShell profile

Completions include context-aware values — --status suggests valid status values, --type suggests valid types, and --format suggests text or json.

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:

{"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:

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

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

# 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

# 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

# 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)	—

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

dcy config reset --yes
dcy auth login
dcy org set <org-id>

Getting Started

Commands

Examples

Version & Updates

Check Version

Check for Updates

Update

JSON Output

Configuration

View Configuration

Get / Set Values

Clear a Value

Reset Configuration

Import from Legacy CLI

Environment Management

List Environments

Switch Environment

Environment Variables

Automatic Retry

Health Check

What it checks

JSON Output

Shell Completions

Bash

Zsh

Fish

PowerShell

Troubleshooting

Error Format

Token Expired

Wrong Organization

Missing Configuration

Connection Issues

Exit Codes

Reset Everything

Next Steps

Authentication

Organizations

​Version & Updates

​Check Version

​Check for Updates

​Update

​JSON Output

​Configuration

​View Configuration

​Get / Set Values

​Clear a Value

​Reset Configuration

​Import from Legacy CLI

​Environment Management

​List Environments

​Switch Environment

​Environment Variables

​Automatic Retry

​Health Check

​What it checks

​JSON Output

​Shell Completions

​Bash

​Zsh

​Fish

​PowerShell

​Troubleshooting

​Error Format

​Token Expired

​Wrong Organization

​Missing Configuration

​Connection Issues

​Exit Codes

​Reset Everything

​Next Steps

Authentication

Organizations

Version & Updates

Check Version

Check for Updates

Update

JSON Output

Configuration

View Configuration

Get / Set Values

Clear a Value

Reset Configuration

Import from Legacy CLI

Environment Management

List Environments

Switch Environment

Environment Variables

Automatic Retry

Health Check

What it checks

JSON Output

Shell Completions

Bash

Zsh

Fish

PowerShell

Troubleshooting

Error Format

Token Expired

Wrong Organization

Missing Configuration

Connection Issues

Exit Codes

Reset Everything

Next Steps