Configuration & Secrets

The Chanl CLI stores configuration in a local file and supports environment variable overrides. This page covers authentication methods, config management, secrets, and multi-environment workflows.

Config File

All CLI configuration is stored in ~/.chanl/config.json. The CLI creates this file automatically on first use.

chanl config path

/Users/you/.chanl/config.json

What's stored

The config file holds your authentication credentials, workspace context, and display preferences. Sensitive values (API keys, tokens) are stored in plaintext -- protect this file with standard filesystem permissions.

{
  "apiKey": "ak_live_abc123...",
  "baseUrl": "https://platform.chanl.ai",
  "workspaceId": "ws_abc123",
  "defaultFormat": "table"
}

Reset config

To start fresh, delete the config file:

rm ~/.chanl/config.json

The CLI recreates it with defaults on the next command.

Authentication

The CLI supports two authentication methods: browser login (OAuth) and API key.

chanl login

Opening browser for authentication...
If the browser didn't open, visit:
  https://app.chanl.ai/cli-auth?port=54321

✓ Authentication successful

User:       dean@acme.com
Name:       Dean Grover
Workspace:  ws_abc123

✓ Credentials saved to /Users/you/.chanl/config.json

? Select a workspace:
> Acme Corp (ws_abc123) - owner
  Side Project (ws_def456) - member

chanl login --api-key ak_live_abc123def456

✓ Authentication successful
✓ API key saved to /Users/you/.chanl/config.json

Check auth status

chanl auth status

Status:        Authenticated
Method:        API Key
API Key:       ak_li****f456
Base URL:      https://platform.chanl.ai
Workspace ID:  ws_abc123
Workspace:     Acme Corp

Log out

chanl logout

✓ Logged out successfully

Logout removes all stored credentials (API key, JWT token, refresh token) and clears the workspace ID.

API Keys

Format

Chanl API keys use the prefix ak_ followed by an environment indicator and a random string:

Create an API key

API keys are created in the Chanl dashboard, not from the CLI.

chanl login --api-key ak_live_abc123def456

Rotation

To rotate a key, create a new one in the dashboard, update your CLI config or CI secrets, then delete the old key. There is no automatic rotation -- you control the lifecycle.

# Update the CLI with a new key
chanl login --api-key ak_live_new_key_here

# Or set via environment variable (no config change needed)
export CHANL_API_KEY=ak_live_new_key_here

Config Commands

List all config

chanl config list

Key              Value                           Source
apiKey           ak_li****f456                   config
baseUrl          https://platform.chanl.ai       default
workspaceId      ws_abc123                       config
defaultFormat    table                           default

Config file: /Users/you/.chanl/config.json

The Source column shows where each value comes from:

Get a single value

chanl config get baseUrl

https://platform.chanl.ai

Set a value

chanl config set defaultFormat json

✓ Set defaultFormat = json

Delete a value

chanl config delete workspaceId

✓ Deleted workspaceId

config delete and config unset are aliases -- both work.

Switch environment

Reset the base URL to production:

chanl config use production

✓ Switched to production: https://platform.chanl.ai

For custom endpoints, set the base URL directly:

chanl config set baseUrl https://platform-staging.chanl.ai

Config Keys

Environment Variables

Environment variables override config file values. This is the recommended approach for CI/CD pipelines and containers.

Priority order

For keys that support environment variable overrides, the resolution order is:

Environment variable > Config file > Built-in default

For example, if CHANL_API_KEY is set, it takes precedence over the apiKey value in ~/.chanl/config.json -- even if the config file has a different key.

CI/CD example

steps:
  - name: Run scenario tests
    run: chanl scenarios run sc_abc123 --json
    env:
      CHANL_API_KEY: ${{ secrets.CHANL_API_KEY }}
      CHANL_WORKSPACE_ID: ${{ vars.CHANL_WORKSPACE_ID }}

Shell profile example

Add to ~/.zshrc or ~/.bashrc for persistent overrides:

export CHANL_API_KEY=ak_live_abc123def456
export CHANL_WORKSPACE_ID=ws_abc123

Tool Secrets

Tools in Chanl can reference secrets using the {{secret:name}} syntax in their configuration. These secrets are managed entirely through the platform UI -- the CLI does not create or modify them.

How secrets work

When you define an HTTP tool, you can reference secrets in headers, query parameters, or the request body:

{
  "name": "weather-api",
  "type": "http",
  "configuration": {
    "url": "https://api.weather.com/v1/forecast",
    "headers": {
      "Authorization": "Bearer {{secret:WEATHER_API_KEY}}"
    }
  }
}

At runtime, the platform resolves {{secret:WEATHER_API_KEY}} to the actual value stored in the workspace's secret store. The secret value never appears in logs, API responses, or tool definitions.

Managing secrets

Secrets are scoped to a workspace and managed in the Chanl dashboard:

View secrets from the CLI

You can list tools that reference secrets, but you cannot read secret values:

chanl tools get tool_abc123 --json | jq '.configuration.headers'

{
  "Authorization": "Bearer {{secret:WEATHER_API_KEY}}"
}

The {{secret:...}} placeholder is visible. The resolved value is not.

Provider Setup

LLM, speech-to-text (STT), and text-to-speech (TTS) provider API keys are configured through the Chanl dashboard, not the CLI.

Go to Settings > Integrations in the Chanl dashboard to connect providers:

Once connected, your agents and tools use these providers automatically. No CLI configuration is needed.

Multiple Environments

Switch between environments

Use config set baseUrl to point the CLI at different environments:

chanl config use production

chanl config set baseUrl https://platform.chanl.ai

chanl config set baseUrl https://chanl-platform-staging.fly.dev

chanl config set baseUrl https://your-custom-instance.example.com

Per-command overrides

Use environment variables for one-off commands without changing your config:

CHANL_BASE_URL=https://chanl-platform-staging.fly.dev chanl agents list

Login with a custom base URL

The --base-url flag on login sets the base URL and authenticates in one step:

chanl login --base-url https://chanl-platform-staging.fly.dev --api-key ak_test_staging_key

SDK Configuration

When using the Chanl SDK programmatically (outside the CLI), you pass configuration directly to the constructor:

import { ChanlSDK } from '@chanl/sdk';

const chanl = new ChanlSDK({
  baseUrl: 'https://platform.chanl.ai',
  apiKey: 'ak_live_abc123def456',
  timeout: 30000,
  retry: {
    maxRetries: 3,
    retryDelay: 1000,
    backoffMultiplier: 2,
  },
});

Troubleshooting

Related