---
source: CrewKit documentation
url: https://crewkit.io/docs/configuration.md
title: "Configuration"
description: "Configure crewkit with environment variables, config files, and CI/CD settings."
---


import { Callout } from 'fumadocs-ui/components/callout';

crewkit is configured through environment variables and local config files. Most settings have sensible defaults — you only need to change things for CI/CD or multi-environment setups.

---

## Environment variables

| Variable | Description | Default |
|----------|-------------|---------|
| `CREWKIT_API_URL` | API base URL | `https://api.crewkit.io` |
| `CREWKIT_ORG` | Organization slug (skips auto-detection) | — |
| `CREWKIT_REPOSITORY_ID` | Repository ID (skips detection) | — |
| `CREWKIT_ENV` | Environment name (used for error reporting) | `production` |
| `NO_COLOR` | Disable colored output | — |

---

## Local config file

When you run `crewkit init` or `crewkit code` for the first time in a repo, crewkit creates a `.crewkit/config.toml` file (gitignored):

```toml
version = 1

[repository]
id = "repo_abc123"
remote_url = "git@github.com:acme/frontend"
linked_at = "2026-01-20T10:30:00Z"

[component]
detected = "dashboard"
override = null

[sync]
last_sync = "2026-01-20T10:35:00Z"
agents = ["frontend-expert", "api-designer"]
```

This file caches your repo-to-project mapping so subsequent runs skip the detection step.

<Callout type="info">
If you move your repo or change the git remote, crewkit invalidates the cache and re-prompts.
</Callout>

---

## CI/CD mode

For non-interactive environments (GitHub Actions, GitLab CI, etc.), combine `--yes` with environment variables:

```bash
# Set in your CI environment
export CREWKIT_REPOSITORY_ID=repo_abc123

# Run without prompts
crewkit code --yes --prompt "Run the test suite and fix failures"
```

crewkit auto-detects non-TTY environments and provides a helpful error if interactive prompts are needed but unavailable.

---

## Headless mode

Run one-shot prompts for scripting and automation:

```bash
# Run a one-shot prompt
crewkit code --prompt "Add error handling to api/auth.rs"

# JSON output for parsing
crewkit code --prompt "List all TODO comments" --output-format json

# Stream JSON for real-time processing
crewkit code --prompt "Refactor the user model" --output-format stream-json

# Set a timeout (default: 300 seconds)
crewkit code --prompt "Fix the failing test" --timeout 600
```

---

## Display options

```bash
# Disable colors
crewkit --no-color code

# ASCII-only output (no unicode symbols)
crewkit --plain code

# Verbose output (file lists, timing details)
crewkit code --verbose
```

---

## Debug logging

Enable debug logs for troubleshooting:

```bash
crewkit code --debug
```

Logs are written to `.crewkit/debug-latest.log` in your project root. Follow them in another terminal:

```bash
tail -f .crewkit/debug-latest.log
```

---

## Next steps

- [Troubleshooting](/docs/troubleshooting)
- [CLI command reference](/docs/cli)