The Carotene CLI (carrot)

In traditional development, you piece together a toolchain: you use npm to install dependencies, tsc to compile TypeScript, jest to run tests, and prisma to manage database schemas.

Carotene replaces all of this with a single, unified binary: the Carotene CLI.

The CLI is the engine that bridges the gap between your human-readable architectural blueprints (.carrot files) and the final, production-ready microservices. It acts as the compiler, the test runner, and the AI agent.

Core Commands

carrot init <project-name>

The Dynamic Scaffolder

This command initializes a blank Carotene workspace. It sets up your global carotene.toml configuration and creates your first system.carrot blueprint. It does not generate rigid framework folders; instead, it waits for you to define your architecture, and then dynamically scaffolds the monorepo to perfectly match your definitions.

It also automatically generates a .clinerules file in the project root. This ensures that any external AI coding assistants you use are immediately aware of Carotene's architectural rules and strict Zero-Trust constraints.

carrot dev

The Autonomic Development Loop

This is the command you will use 99% of the time. It starts the Test-Driven Generation (TDG) engine in watch mode. When you save a .carrot file (or a src/ file), carrot dev triggers the autonomic loop:

1. Provisions the Vapor Sandbox.
2. Performs Hash-Detection: Checks if you manually edited any AI-owned src/ files and prompts you to claim @manual ownership if necessary.
3. Prompts the authenticated LLM to fill in your @(...) Generative Operators for AI-owned blocks.
4. Runs your test blocks against the generated code.
5. Autonomously feeds failures back to the LLM until the assertions pass.

Example Output:

$ carrot dev

[~] Parsing system.carrot...
[~] Provisioning embedded PGLite sandbox...
[~] Generating logic for CoreAPI.ProcessRefund() ...
[!] Assertion Failed: Expected 95.0, Got 100.0. Retrying (Attempt 2/5)...
[✔] Logic Verified.
[✔] Zero-Trust Guardrails Enforced.
[🚀] CoreAPI running on http://localhost:4000

carrot build

The Production Compiler

While carrot dev creates implementation stubs and runs tests, carrot build is meant for your CI/CD pipeline. It strictly verifies that every test passes, every @(...) operator is successfully implemented, and every Zero-Trust boundary is respected. It then compiles the raw, dependency-free TypeScript or Go code into the .generated/ folders, ready for deployment.

As part of the build pipeline, carrot build also automatically executes carrot generate:docs, outputting comprehensive API documentation and architecture maps into a .docs/ folder (this behavior can be opted out of in carotene.toml).

Security & Inspection Commands

Because Carotene's core philosophy is built around the Zero-Trust Sandbox, the CLI provides powerful tools to visualize and audit your system's security perimeter.

carrot inspect <function-name>

The Blast Radius Auditor

When reviewing code, security engineers need to know exactly what a function can touch. This command statically analyzes a function's verbs (reads, updates, calls) and outputs a clear visual matrix of its permissions.

Example Output:

$ carrot inspect ProcessRefund

🔍 Security Audit: CoreAPI.ProcessRefund
--------------------------------------------------
[✔] READS    : store.Order, store.Customer
[✔] UPDATES  : store.Order
[✔] CALLS    : integration.Stripe
[✖] CREATES  : (None)
[✖] DELETES  : (None)

🔒 RBAC Rules applied: 
  - requires session.role == Admin
--------------------------------------------------
Status: Secure. Sandbox strictly bounded.

carrot login

Carotene Cloud Authentication

Authenticates your CLI with the Carotene Managed Cloud. This is used if your carotene.toml is set to mode = "managed". It provisions a secure token allowing the compiler to use Carotene's hosted, highly optimised generation pipeline without you needing to manage individual Anthropic or OpenAI billing accounts.

Configuration Management

carrot keys

BYOK Secrets Manager

If you are using mode = "byok", you should not hardcode your API keys into your .carrot or .toml files. The keys command securely stores your third-party LLM tokens in your operating system's native secure enclave (e.g., macOS Keychain, Windows Credential Manager).

$ carrot keys:add anthropic <your-api-key>
$ carrot keys:list
  [✔] anthropic (Configured)
  [ ] openai    (Missing)
$ carrot keys:remove anthropic

carrot generate:sdk <target>

If you are building a decoupled frontend (like a mobile app) that lives outside the Carotene monorepo, you can use this command to instantly generate a strongly-typed client SDK based on your backend blueprints.

carrot generate:sdk swift --out ./ios-app/Network
carrot generate:sdk kotlin --out ./android-app/API