Configuration

Complete environment variable reference

Configuration

Clotion is configured via environment variables in a .env file.

Important: The .env file must be in the current working directory when you run clotion. Always run the command from the cloned repository folder where your .env file is located.

Setup

Copy the example configuration and edit it:

cp .env.example .env

Required Variables

Notion Integration

Repository

Notion Status Values

Important: Status values must match your Notion Status property exactly (case-sensitive). Check your database for the correct spelling.

Optional Variables

Polling Settings

Task Settings

Worktrees

Logging

Example Configuration

# .env file

# Notion Integration
# Get your token from https://www.notion.so/my-integrations
# Token starts with 'secret_' (older) or 'ntn_' (newer)
NOTION_API_KEY=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
NOTION_DATABASE_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Status Values (must match your Notion Status property EXACTLY)
NOTION_STATUS_BACKLOG=Backlog
NOTION_STATUS_TODO=ToDo
NOTION_STATUS_IN_PROGRESS=In Progress
NOTION_STATUS_IN_REVIEW=In Review
NOTION_STATUS_DONE=Done

# Repository
REPO_PATH=/Users/yourname/projects/myapp

# Task Settings
MAX_CONCURRENT_TASKS=3
BLOCKED_TIMEOUT=7200

# Logging
LOG_LEVEL=INFO

Creating a Notion Integration

1. Go to notion.so/my-integrations
2. Click + New integration
3. Configure:
   • Name: Clotion
   • Associated workspace: Select your workspace
   • Capabilities: Read content, Update content, Insert content
4. Click Submit
5. Copy the Internal Integration Token

Finding Your Database ID

Your database ID is found in the URL when viewing your Notion database as a full page.

From the browser URL:

https://www.notion.so/workspace/abc123def456789012345678901234?v=...
                               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                               This is your database ID (32 characters)

Tips:

• The ID is 32 characters without hyphens
• It appears right before the ?v= query parameter
• If using a database inside a page, click ... → Open as full page first

Sharing Your Database

Your Notion integration needs access to the database:

1. Open your database in Notion
2. Click ... in the top right corner
3. Click Add connections
4. Search for your integration name ("Clotion")
5. Click to add it

Note: You only need to do this once per database.

Required Database Properties

Clotion requires a Status property on your database. This can be either:

• The newer Status type (with groups)
• The classic Select type

On first run, Clotion will auto-create these additional properties:

Your Status property should have these options (or customize via env vars):

• Backlog
• ToDo
• In Progress
• In Review
• Done

Common Issues

"API key should start with 'secret_' or 'ntn_'"

Notion tokens come in two formats:

• Older integrations: secret_...
• Newer integrations: ntn_...

Both are valid. Make sure you copied the full token.

Status changes not detected

Status values are case-sensitive. Common issue: ToDo vs Todo vs To Do.

Check your Notion database for the exact spelling of each status option.

"Provided ID is a page, not a database"

You copied a page ID instead of the database ID. Open your database as a full page and copy the ID from that URL.