AI Writing Guide

import { Aside } from ‘@astrojs/starlight/components’;

This page is for AI assistants and code generators that need to produce valid CCL. If you’re implementing a CCL parser, see the AI Quickstart instead.

CCL Output Rules

When generating CCL text, follow these rules exactly:

1. One entry per line: key = value
2. First = splits key from value: Everything after the first = is the value
3. Indent with 2 spaces for nested content (consistent indentation is required, 2 spaces is conventional)
4. Empty keys for lists: = item (no key before =)
5. Comments: /= text on its own line (no inline comments)
6. No quoting: Values are literal strings. Never add quotes around values
7. No escaping: There are no escape sequences. Write characters literally
8. No trailing commas, braces, or brackets: CCL uses indentation, not delimiters

Generating CCL from Structured Data

From JSON/Object to CCL

Given this JSON:

{
  "server": {
    "host": "0.0.0.0",
    "port": "8080"
  },
  "name": "MyApp"
}

Produce:

server =
  host = 0.0.0.0
  port = 8080
name = MyApp

From Arrays to CCL Lists

Given this JSON:

{
  "servers": ["web1.example.com", "web2.example.com"]
}

Produce:

servers =
  = web1.example.com
  = web2.example.com

Nested Objects with Arrays

Given this JSON:

{
  "deploy": {
    "regions": ["us-east-1", "eu-west-1"],
    "strategy": "rolling"
  }
}

Produce:

deploy =
  regions =
    = us-east-1
    = eu-west-1
  strategy = rolling

Common Generation Mistakes

Adding Quotes

/= WRONG: Don't quote values
name = "My Application"
port = "8080"

/= CORRECT: Values are literal strings
name = My Application
port = 8080

Using JSON/YAML Syntax

/= WRONG: No braces, brackets, or colons
server = { host: "localhost", port: 8080 }
items = ["a", "b", "c"]

/= CORRECT: Use indentation and empty keys
server =
  host = localhost
  port = 8080
items =
  = a
  = b
  = c

Inline Comments

/= WRONG: No inline comments
port = 8080  # default port
host = localhost  /= main server

/= CORRECT: Comments on their own line
/= Default port
port = 8080
/= Main server
host = localhost

Dot-Separated Key Paths

/= WRONG: Dots are literal characters, not path separators
database.host = localhost
database.port = 5432

/= CORRECT: Use indentation for hierarchy
database =
  host = localhost
  port = 5432

Dotted keys like `database.host` are valid CCL but they create a **literal key** named `"database.host"`, not a nested structure. This is almost never what you want when generating configuration.

Escape Sequences

/= WRONG: No escape sequences exist
message = Hello\nWorld
path = C:\\Users\\admin

/= CORRECT: Write literal characters
message = Hello
  World
path = C:\Users\admin

Type Handling

All CCL values are strings. When generating CCL from typed data:

Source type	CCL output	Example
String	As-is	name = Alice
Integer	Decimal string	port = 8080
Float	Decimal string	rate = 0.95
Boolean	true or false	debug = true
Null/None	Empty value	optional =
Array	Empty-key list	= item per element
Object	Indented section	Nested key-value pairs

Validation Checklist

Before returning generated CCL, verify:

• Every entry has exactly the format key = value or = value (list item) or /= text (comment)
• No quotes around values
• No braces, brackets, or trailing commas
• Indentation is consistent (2 spaces per level)
• Comments are on their own lines, starting with /=
• Nested structures use indentation, not dot-separated keys
• Arrays use empty-key syntax (= item), not repeated keys with the same name at the same level (both work, but empty keys are conventional inside sections)

Full Example

A complete CCL configuration file demonstrating all patterns:

/= Application configuration
/= Generated by deployment tool

app =
  name = order-service
  version = 3.2.1
  environment = production

server =
  host = 0.0.0.0
  port = 8080
  workers = 4

database =
  host = db.prod.internal
  port = 5432
  name = orders
  pool_size = 20
  ssl = true

cache =
  driver = redis
  host = cache.prod.internal
  port = 6379
  ttl = 3600

allowed_origins =
  = https://app.example.com
  = https://admin.example.com
  = https://api.example.com

logging =
  level = info
  format = json
  outputs =
    stdout =
      enabled = true
    file =
      enabled = true
      path = /var/log/orders/app.log
      rotation = daily

feature_flags =
  new_checkout = true
  beta_api = false
  /= Rollout started 2025-02-20
  progressive_loading = true