Chronos — CLI Reference

Chronos Documentation: ← Introduction | Language Reference | ← Examples & Artifacts | CLI Reference

CLI and Workflow

The Chronos CLI (chronos) validates your specifications and executes the projections defined in chronos-build.json. It runs the same way locally, in CI, or as part of a build pipeline.

Global flags available on every command:

Click any command to expand its full documentation.

chronos init -t quickstart -o ./my-requirements

# List available templates
chronos init --list

# Create project from a template
chronos init -t e-commerce -o ./requirements

# Use a custom template repository
chronos init --url https://github.com/my-org/chronos-templates -t internal-standard -o ./requirements

chronos validate
chronos validate requirements/checkout/
chronos validate requirements/checkout/guest-checkout.chronos

ERROR [CHR-001] requirements/checkout/guest-checkout.chronos:12
  Journey 'GuestCheckout' does not declare an actor.

WARNING [CHR-009] requirements/checkout/guest-checkout.chronos:8
  Journey 'GuestCheckout' has no @kpi trait. Consider linking to a business metric.

WARNING [CHR-004] requirements/checkout/guest-checkout.chronos:34
  Expectation contains ambiguous language: "quickly". Use measurable language instead.

chronos build
chronos build --projection issues
chronos build --projection tests,diagrams

CHRONOS_LINEAR_TOKEN=xxx chronos build
CHRONOS_JIRA_TOKEN=xxx chronos build

chronos select 'journey'
chronos select 'journey[trait|compliance]'
chronos select 'actor' requirements/

# List all journey IDs
chronos select 'journey'
# com.genairus.commerce.checkout#GuestCheckout
# com.genairus.commerce.checkout#ReturnCustomerCheckout
# com.genairus.onboarding#EmailSignup

# Find all compliance-tagged journeys
chronos select 'journey[trait|compliance]'

# Find journeys missing a KPI
chronos select 'journey:not([trait|kpi])'

# Find all PII entities
chronos select 'entity[trait|pii]'

# Output as JSON for scripting
chronos select 'journey' --format json

chronos diff --old v1/requirements/ --new v2/requirements/
chronos diff --old main --new feature/checkout-v2 --mode git

BREAKING  Journey 'GuestCheckout' step 'PlaceOrder' expectation changed
          - "Order is created with status PAID and confirmation email is queued"
          + "Order is created with status PENDING and payment is processed asynchronously"

ADDED     Journey 'ExpressCheckout' added in com.genairus.commerce.checkout

REMOVED   Actor 'GuestUser' removed from com.genairus.common.actors
          ↳ Referenced by: GuestCheckout, ExpressCheckout

chronos clean
chronos clean --projection issues

Running in CI / Build Pipelines

chronos build is designed to run unattended. Add it to any pipeline:

# .github/workflows/chronos.yml
name: Chronos Build
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Chronos CLI
        run: |
          curl -L https://github.com/genairus/chronos/releases/latest/download/chronos-linux-x86_64.zip \
          -o chronos.zip && unzip chronos.zip && sudo mv chronos /usr/local/bin/
      - name: Validate
        run: chronos validate
      - name: Diff against main
        run: chronos diff --old origin/main --new HEAD --mode git
      - name: Build artifacts
        run: chronos build
        env:
          CHRONOS_LINEAR_TOKEN: ${{ secrets.LINEAR_API_TOKEN }}

Build Configuration

chronos-build.json is the single configuration file that controls everything Chronos produces. Each entry in projections is a named plugin. You pick which ones to enable—if a projection isn't listed, it isn't run.

Issue tracker plugins (use one):

Test scaffolding plugins (use one):

Document plugins:

{
  "version": "1.0",
  "sources": ["requirements/**/*.chronos"],
  "projections": {
    "issues": {
      "plugin": "linear",
      "config": {
        "teamId": "PRODUCT"
      }
    },
    "prd": {
      "plugin": "prd",
      "output": "./artifacts/docs",
      "config": {
        "format": "markdown",
        "includeKpis": true,
        "includeCompliance": true
      }
    },
    "tests": {
      "plugin": "cucumber",
      "output": "./features",
      "config": {
        "language": "en",
        "indentSize": 2
      }
    },
    "diagrams": {
      "plugin": "mermaid",
      "output": "./artifacts/diagrams",
      "config": {
        "theme": "default"
      }
    },
    "telemetry": {
      "plugin": "event-contracts",
      "output": "./artifacts/telemetry",
      "config": {
        "format": "yaml"
      }
    }
  },
  "integrations": {
    "capacitor": {
      "schema": "./data"
    },
    "smithy": {
      "spec": "./api"
    }
  }
}

Every projection that calls an external API (issue trackers) reads its credentials from environment variables. The chronos-build.json file is safe to commit—no secrets belong in it.

Validation Rules

Chronos enforces semantic rules:

Common Validation Errors

Error: Ambiguous expectation

expectations must not contain fuzzy language like "fast", "easy", "intuitive"

Fix: Use concrete, measurable language:

• ❌ "System responds quickly"
• ✅ "System responds within 500ms (p99)"

Error: Unresolved shape reference

Entity 'Order' is not defined in namespace 'com.example'

Fix: Add import or define the entity:

use com.example.entities#Order

Error: Journey lacks terminal outcome

Journey 'GuestCheckout' has paths that don't reach a terminal state

Fix: Ensure all steps and variants lead to outcomes.success or outcomes.failure.

Troubleshooting

Common Issues

Issue: "Namespace not found" error

Error: Cannot resolve shape 'Order' from namespace 'com.example.data'

Solution:

1. Check that the namespace is correct in your use statement
2. Verify the file defining Order exists and has the correct namespace declaration
3. Ensure the source directory is included in chronos-build.json sources array

Issue: Fuzzy language warnings

Warning: Step expectation contains ambiguous language: "quickly", "easily"

Solution: Replace with concrete, measurable language:

• "responds quickly" → "responds within 500ms (p99)"
• "displays clearly" → "displays error message in red text above form"
• "handles errors gracefully" → "returns 400 status with JSON error object"

Issue: Journey doesn't validate

Error: Journey 'GuestCheckout' has unreachable terminal state

Solution: Trace all paths through your journey:

1. Every step should either lead to another step or to a terminal outcome
2. Every variant should specify an outcome field
3. Use TransitionTo() or ReturnToStep() to create explicit paths

Issue: Generated work items missing fields or failing to push

Solution: Check your issue tracker plugin configuration in chronos-build.json. Each plugin has its own required config keys—refer to the plugin's documentation. Example for jira-cloud:

{
  "projections": {
    "issues": {
      "plugin": "jira-cloud",
      "config": {
        "projectKey": "ECOM",           // Must match your Jira project key
        "issueTypeEpic": "Epic",        // Must match Jira issue type name exactly
        "issueTypeStory": "Story",
        "customFields": {
          "KPI": "customfield_10001"    // Map Chronos traits to custom fields
        }
      }
    }
  }
}

Getting Help

• Documentation: /docs/chronos
• Generators: /docs/chronos-generators
• GitHub Issues: github.com/genairus/chronos/issues
• Discord: Coming soon!

Chronos Documentation: ← Introduction | Language Reference | ← Examples & Artifacts | CLI Reference