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 introspect <path>

The Reverse-Architecture Engine

If you have an existing application, you do not need to write your .carrot files from scratch. Point this command at your legacy src/ directory. The AI will ingest your entire codebase, map the dependency graphs, identify your database schemas, and output a complete suite of .carrot blueprints representing your current architecture.

The Safety Guarantee: Every function, frontend view, and loop generated by this command is automatically flagged with the @manual decorator. This ensures that running carrot generate will never overwrite your existing code. It simply maps your architecture, allowing you to gradually migrate specific functions to @ai ownership one endpoint at a time.

carrot dev

Static Analysis and Zero-Trust Linting

This is the command you will run frequently during contract writing. It costs $0 and uses zero AI tokens. carrot dev instantly verifies your types, paths, and verbs across the entire architecture.

1. Ensures all referenced models and properties exist.
2. Verifies that functions declare the correct Zero-Trust verbs (reads, calls, etc.) for their internal logic constraints.
3. Checks for cyclic dependencies and domain isolation violations.

carrot generate

The Autonomic Development Loop

This is the command that actually invokes the LLM. It starts the Test-Driven Generation (TDG) engine in watch mode. When you save a .carrot file (or a src/ file), carrot generate 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 synthesize your @(...) Generative Operators against your ensures rules and test 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 generate

[~] 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