Authentication - Dcycle Platform Docs

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

Logging In

The CLI uses the same credentials as the Dcycle web application.

dcy auth login

This opens your default browser to the Dcycle sign-in page. You complete the full authentication flow in the browser (email, password, MFA, SSO) and the CLI receives the session automatically. Output:

Logged in
  User:         john@company.com
  Organization: Acme Corp
  Host:         https://api.dcycle.io (PROD)

If you have access to multiple organizations, the CLI prompts you to choose:

Available organizations:
  1. Acme Corp
  2. Acme Logistics
Select organization: 1

Browser login handles all authentication methods including SSO and MFA — no extra steps needed in the terminal.

If the browser can’t be opened automatically, the CLI prints a URL for you to open manually. Use --no-browser to authenticate directly in the terminal:

dcy auth login --no-browser

This prompts for email and password interactively. If your account has MFA enabled, the CLI also prompts for your TOTP code.

Terminal mode is used automatically when --email or --password flags are provided, or when stdin is not a TTY (e.g. in CI/CD pipelines).

For automation and scripting:

dcy auth login --email user@example.com --password your_password

Flag	Short	Default	Description
`--email`	`-e`	—	Email address
`--password`	`-p`	—	Password
`--host`	—	—	Host alias or URL (e.g. `prod`, `staging`)
`--no-browser`	—	`false`	Use terminal prompts instead of browser login

Avoid storing passwords in scripts. Consider using environment variables or secure secret management.

API Key Authentication

For CI/CD pipelines, scripts, and non-interactive environments, use API key authentication instead of browser login.

Setting Up an API Key

Store an API key in your local config:

dcy auth set-api-key <your-api-key>

Output:

API key saved
  Host:         https://api.dcycle.io (PROD)
  Organization: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9

If no organization is set yet, the CLI shows a tip:

API key saved
  Host:         https://api.dcycle.io (PROD)
  Tip: set organization with `dcy org set <org-id>` or DCYCLE_ORG_ID env var

If no host is configured yet, specify it with --host:

dcy auth set-api-key <your-api-key> --host prod

Using Environment Variables

You can also authenticate entirely via environment variables — no config file needed:

export DCYCLE_API_KEY=your_api_key
export DCYCLE_HOST=https://api.dcycle.io
export DCYCLE_ORG_ID=your_organization_id

dcy vehicle list
dcy facility list

When DCYCLE_API_KEY is set, the CLI uses x-api-key header authentication instead of Bearer tokens. This is the recommended approach for CI/CD pipelines.

CI/CD Example (GitHub Actions)

env:
  DCYCLE_API_KEY: ${{ secrets.DCYCLE_API_KEY }}
  DCYCLE_ORG_ID: ${{ secrets.DCYCLE_ORG_ID }}
  DCYCLE_HOST: https://api.dcycle.io

steps:
  - name: Upload vehicle data
    run: dcy vehicle upload --file vehicles.csv --dry-run

  - name: Check facility emissions
    run: dcy facility list --format json

Auth Method Priority

When both an API key and a login token are available, the API key takes precedence:

API key (DCYCLE_API_KEY env var or api_key in config) — uses x-api-key header
Login token (dcy auth login) — uses Authorization: Bearer header

Config File with API Key

# ~/.config/dcycle/v2/config.yaml
host: https://api.dcycle.io
api_key: your_api_key_here
organization_id: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9

Checking Session Status

View your current authentication state:

dcy auth status

Output:

Authentication status
  Host:            https://api.dcycle.io (PROD)
  User:            john@company.com
  Name:            John Doe
  Organization:    Acme Corp
  Organization ID: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9
  Auth method:     token
  Authenticated:   yes

When using an API key, Auth method shows api_key instead of token. When not authenticated:

Not authenticated

Verifying Credentials

Use --check to verify your stored credentials are still valid by calling the API:

dcy auth status --check

When the session is valid:

Authentication status
  Host:            https://api.dcycle.io (PROD)
  User:            john@company.com
  Organization:    Acme Corp
  Organization ID: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9
  Auth method:     token
  Session:         valid

When the session has expired (exit code 2):

Authentication status
  Host:            https://api.dcycle.io (PROD)
  User:            john@company.com
  Auth method:     token
  Session:         expired
Error: session expired or invalid; run `dcy auth login`

Use --check in CI/CD pipelines to validate credentials before running commands:

dcy auth status --check || dcy auth login --email "$EMAIL" --password "$PASSWORD"

Flag	Default	Description
`--check`	`false`	Verify credentials against the API

JSON Response

dcy auth status --format json

{
  "authenticated": true,
  "auth_method": "token",
  "host": "https://api.dcycle.io",
  "environment": "PROD",
  "user": "john@company.com",
  "name": "John Doe",
  "organization": "Acme Corp",
  "organization_id": "ff4adcc7-8172-45fe-9cf1-e90a6de53aa9"
}

With --check, the JSON response includes valid and check_error fields:

dcy auth status --check --format json

{
  "authenticated": true,
  "auth_method": "token",
  "host": "https://api.dcycle.io",
  "environment": "PROD",
  "user": "john@company.com",
  "name": "John Doe",
  "organization": "Acme Corp",
  "organization_id": "ff4adcc7-8172-45fe-9cf1-e90a6de53aa9",
  "valid": true
}

# Extract the current organization for scripts
ORG_ID=$(dcy auth status --format json | jq -r '.organization_id')

Logging Out

dcy auth logout

Output:

Logged out

If not currently logged in:

Not currently logged in

This removes your stored credentials from the local configuration.

Configuring Environments

The CLI can connect to different Dcycle environments.

List Available Hosts

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

Each row shows: alias, URL, environment, and yes if it’s the current host.

JSON Response

dcy config host list --format json

[
  {
    "alias": "production",
    "url": "https://api.dcycle.io",
    "environment": "PROD",
    "active": true
  },
  {
    "alias": "staging",
    "url": "https://api.stg.dcycle.io",
    "environment": "STAGING",
    "active": false
  },
  {
    "alias": "dev",
    "url": "https://api.dev.dcycle.io",
    "environment": "DEV",
    "active": false
  },
  {
    "alias": "local",
    "url": "http://localhost:8000",
    "environment": "LOCAL",
    "active": false
  }
]

Switch Environment

# Production (default)
dcy config host set production

# Staging environment
dcy config host set staging

# Development environment
dcy config host set dev

# Local development
dcy config host set local

Output:

host set to https://api.dcycle.io (PROD)

Both prod and production resolve to the same URL. Use whichever you prefer.

Development and staging environments automatically disable SSL verification for self-signed certificates.

Configuration Management

Show Current Configuration

# Human-readable YAML format (tokens redacted)
dcy config show

# JSON format
dcy config show --format json

List Config Values

Quick summary of host, environment, user, and organization:

dcy config list

Output:

Host: https://api.dcycle.io
Environment: PROD
User: john@company.com
Organization: Acme Corp
Organization ID: ff4adcc7-...
Token: ***

JSON Response

dcy config list --format json

{
  "host": "https://api.dcycle.io",
  "environment": "PROD",
  "user": "john@company.com",
  "organization": "Acme Corp",
  "organization_id": "ff4adcc7-8172-45fe-9cf1-e90a6de53aa9",
  "has_token": true,
  "has_api_key": false
}

Get / Set Individual Values

# Get a value
dcy config get host
dcy config get organization_id

# Set a value
dcy config set host https://api.dcycle.io

Print Config File Path

dcy config path

Reset Configuration

Remove all stored credentials, tokens, and settings:

# Interactive confirmation
dcy config reset

Confirmation prompt:

Reset config at /home/user/.config/dcycle/v2/config.yaml? All credentials will be removed. [y/N]

Output:

config reset: /home/user/.config/dcycle/v2/config.yaml

Flag	Short	Default	Description
`--yes`	`-y`	`false`	Skip confirmation prompt

# Skip confirmation
dcy config reset --yes

Import from Legacy CLI

If you previously used the Python dc CLI, import your configuration:

# Import (will error if v2 config already exists)
dcy config import-legacy

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

Configuration File

The CLI stores configuration in ~/.config/dcycle/v2/config.yaml:

# ~/.config/dcycle/v2/config.yaml
host: https://api.dcycle.io
token: eyJhbGciOiJIUzI1NiIs...       # set by dcy auth login
api_key: dc_key_abc123...              # set by dcy auth set-api-key (optional)
organization_id: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9
organization_name: Acme Corp
user_email: john@company.com
user_name: John Doe

Configuration Priority

Command-line flags (highest priority)
Environment variables (DCYCLE_API_KEY, DCYCLE_HOST)
Configuration file (~/.config/dcycle/v2/config.yaml)
Defaults (lowest priority)

Environment Variables

For CI/CD and automation:

Variable	Description
`DCYCLE_API_KEY`	API key for authentication (alternative to login)
`DCYCLE_HOST`	Override the API host URL
`DCYCLE_ORG_ID`	Override the active organization
`DCYCLE_FORMAT`	Default output format: `text` or `json`
`DCYCLE_VERBOSE`	Enable verbose HTTP logging (`1` or `true`)
`DCYCLE_TIMEOUT`	HTTP request timeout in seconds (default: `30`)
`NO_COLOR`	Disable ANSI color output when set

# Example: Using API key in CI/CD
export DCYCLE_API_KEY=your_api_key
export DCYCLE_ORG_ID=your_org_id
dcy vehicle list

# Example: Debug mode with JSON output
export DCYCLE_VERBOSE=1
export DCYCLE_FORMAT=json
dcy facility list

CLI Health Check

Run dcy doctor to verify your CLI setup:

dcy doctor

Output:

CLI Health Check

  ✓ Config file — /home/user/.config/dcycle/v2/config.yaml
  ✓ API host — https://api.dcycle.io (PROD)
  ✓ Authentication — Bearer token
  ✓ Organization — Acme Corp (ff4adcc7-...)
  ✓ API connectivity — authenticated as john@company.com
  ✓ Version — v0.0.45 (latest)

All checks passed.

When issues are found:

CLI Health Check

  ✓ Config file — /home/user/.config/dcycle/v2/config.yaml
  ✓ API host — https://api.dcycle.io (PROD)
  ✗ Authentication — not authenticated; run `dcy auth login` or `dcy auth set-api-key`
  ! Organization — not set; run `dcy org set <org-id>`
  ✓ Version — v0.0.45 (latest)

2 issue(s) found.

Icons: ✓ = ok, ! = warning, ✗ = failure. Use --format json for machine-readable output.

Troubleshooting

Permission Errors (403/404)

Verify your session is valid:
dcy auth status --check

Check you’re in the correct organization:

dcy org list
dcy org set <correct-org-id>

Run the health check:
dcy doctor

Token Expired

Check and re-authenticate:

dcy auth status --check   # verify the session is expired
dcy auth login             # re-authenticate

SSL Certificate Errors

For staging/development environments:

dcy config host set staging  # Auto-disables SSL verification

Reset Everything

If the config is corrupted, start fresh:

dcy config reset --yes
dcy auth login

Next Steps

Organizations

Learn how to manage organization context

Configuration

Advanced configuration and environment setup

Examples

See common workflow examples

Overview

Full command reference

​Logging In

​Browser Login (Default)

​Terminal Login

​Non-Interactive Login

​Login Flags

​API Key Authentication

​Setting Up an API Key

​Using Environment Variables

​CI/CD Example (GitHub Actions)

​Auth Method Priority

​Config File with API Key

​Checking Session Status

​Verifying Credentials

​JSON Response

​Logging Out

​Configuring Environments

​List Available Hosts

​JSON Response

​Switch Environment

​Configuration Management

​Show Current Configuration

​List Config Values

​JSON Response

​Get / Set Individual Values

​Print Config File Path

​Reset Configuration

​Import from Legacy CLI

​Configuration File

​Configuration Priority

​Environment Variables

​CLI Health Check

​Troubleshooting

​Permission Errors (403/404)

​Token Expired

​SSL Certificate Errors

​Reset Everything

​Next Steps

Organizations

Configuration

Examples

Overview

Logging In

Browser Login (Default)

Terminal Login

Non-Interactive Login

Login Flags

API Key Authentication

Setting Up an API Key

Using Environment Variables

CI/CD Example (GitHub Actions)

Auth Method Priority

Config File with API Key

Checking Session Status

Verifying Credentials

JSON Response

Logging Out

Configuring Environments

List Available Hosts

JSON Response

Switch Environment

Configuration Management

Show Current Configuration

List Config Values

JSON Response

Get / Set Individual Values

Print Config File Path

Reset Configuration

Import from Legacy CLI

Configuration File

Configuration Priority

Environment Variables

CLI Health Check

Troubleshooting

Permission Errors (403/404)

Token Expired

SSL Certificate Errors

Reset Everything

Next Steps