Configuration
The Contox CLI uses a layered configuration system. Settings can come from three sources, resolved in the following order of precedence (highest first):
- Environment variables
- Project config (
.contox.json) - Global config (
~/.contoxrc)
Command-line flags, when provided, always take the highest precedence and override all other sources.
Global config: ~/.contoxrc
The global configuration file lives in your home directory. It is created and updated by the contox login command.
{
"apiKey": "ctx_abc123...",
"apiUrl": "https://contox.dev",
"teamId": "team_xyz",
"projectId": "proj_abc",
"hmacSecret": "hmac_secret_value"
}
| Field | Description |
|---|---|
apiKey | Your Contox API key, used for authentication with the platform |
apiUrl | The API base URL. Defaults to https://contox.dev if not set |
teamId | Default team ID, used when no project-level config is present |
projectId | Default project ID, used as a fallback |
hmacSecret | HMAC secret for request signing, if applicable |
This file is created automatically when you run:
contox login -k <your-api-key>
Project config: .contox.json
The project configuration file lives in your project root directory. It is created by the contox init command and should be committed to version control so all team members share the same project binding.
{
"teamId": "team_xyz",
"projectId": "proj_abc",
"projectName": "My Project"
}
| Field | Description |
|---|---|
teamId | The team this project belongs to |
projectId | The unique project identifier on the Contox platform |
projectName | A human-readable name for the project |
Create this file by running:
contox init -t <team-id> -n "My Project"
Or link to an existing project:
contox init -t <team-id> -p <project-id>
Environment variables
Environment variables override both config files. They are useful for CI/CD pipelines, Docker containers, and environments where config files are not practical.
| Variable | Maps to | Description |
|---|---|---|
CONTOX_API_KEY | apiKey | API key for authentication |
CONTOX_API_URL | apiUrl | API base URL |
CONTOX_TEAM_ID | teamId | Team identifier |
CONTOX_PROJECT_ID | projectId | Project identifier |
Example: CI/CD usage
export CONTOX_API_KEY="ctx_abc123..."
export CONTOX_TEAM_ID="team_xyz"
export CONTOX_PROJECT_ID="proj_abc"
contox scan --dry-run
contox memory --json
Precedence example
If your ~/.contoxrc has projectId: "proj_a", your .contox.json has projectId: "proj_b", and you set CONTOX_PROJECT_ID=proj_c, the resolved project ID will be proj_c (environment variable wins).
If you then run contox status -p proj_d, the resolved project ID will be proj_d (command-line flag wins over everything).
Verifying your configuration
To see the current resolved configuration:
contox whoami
This shows the config file path, API URL, a masked version of your API key, and your authentication status.