---
title: "A CLI that gates AI agent work — CommitCycle"
description: "cycle is the terminal half of CommitCycle: it files the task, passes the gate, mints a grant bound to one branch, and writes the record at the close."
url: https://commitcycle.com/cli/
language: en
---

# The gate, the grant and the close, from your terminal

> cycle is the terminal half of CommitCycle: it files the task, passes the gate, mints a grant bound to one branch, and writes the record at the close.

CommitCycle CLI Shipped

One command carries a task from a sentence to a branch with access attached, and one carries it back out with a record. Everything in between is ordinary work, done by whichever agent you like.

From a terminal, cycle does each step in one command: start brings the grant onto the machine, submit hands it back.

## Install

```
npm i -g commitcycle
```

The package is `commitcycle` and the command is `cycle`. That split is deliberate: on every Unix machine `cc` is already the system C compiler, so a global `cc` would break `node-gyp` and every Makefile that never overrode `$(CC)`. A governance tool that shadows a compiler is one people uninstall.

## The daily loop

```
cycle start "the thing" \
  --goal "…" --non-goals "…" --criteria "…" \
  --topics backend,frontend        # intake → scope → branch → gate → grant → context
# ... work ...
cycle submit                       # In Progress → In Review, zones closed
cycle verify --close --evidence <url>   # the manifest, the checks, the audit record
```

The four fields are not decoration on that first line: the gate refuses a task without them and leaves it in Todo, so a `start` written without them stops before it opens anything.

Every way into In Progress — `cycle start`, the console's Start button, the connector's `cc_start` — is the same gate. There is no command that opens a zone on its own, which is the point: the moment a second door exists it becomes the one everybody uses in a hurry.

## What it can do

| Command              | What it does                                                                                                                                                          |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `init`               | Set the repository up and write the agent context — memory mode by default (no zones; every edit needs a task), or `--mode governance` to propose zones from the code |
| `start`              | Intake, scope, branch, gate, grant and context, in one call                                                                                                           |
| `status`             | What task is active, and exactly what is open to it right now                                                                                                         |
| `sync`               | Push the zone map and events, pull the grant for this branch                                                                                                          |
| `request-access`     | Ask a zone's owner to open it — with a reason and an alternative                                                                                                      |
| `approve` · `deny`   | Answer a request for a zone you own from the terminal — from a paired machine, only on a one-member board. The console is the stronger door                           |
| `submit` · `pause`   | Hand the work in, or put it down without giving it up                                                                                                                 |
| `verify --close`     | Check the branch against what the task declared, then write the record                                                                                                |
| `seed` · `challenge` | Draft playbooks from the codebase, then argue with them                                                                                                               |
| `doctor`             | Why is CommitCycle behaving like this?                                                                                                                                |

Thirty-seven in `cycle --help`, as of release 0.1.25 (2026-10-12). The full list, flag by flag, is in [the CLI reference](https://commitcycle.com/docs/reference/cli/).

## Where it stops

- **It does not run your agents.** CommitCycle files, gates and records work; what writes the code is whatever you already use.
- **It cannot close past the checks.** `verify --close` checks and records; if the evidence a quality gate names is missing, it refuses and says which.
- **Enforcement is not in the CLI.** Blocking a write as it happens is the hook's job, and the hook arrives with [the editor plugin](https://commitcycle.com/claude-code/). The CLI is the workflow; the plugin is the wall.
- **`discard` does not ask.** It takes a spike back out to its base in one command and reports the proof; `promote`, which keeps what the spike found, asks once.

The command reference is in [the docs](https://commitcycle.com/docs/reference/cli/), and the model it acts on is [the zone map](https://commitcycle.com/zones/).

## Questions this page answers

### Why is the command called cycle and not cc?

On every Unix machine cc is already the system C compiler. A global cc would break node-gyp and every Makefile that never overrode $(CC), and a governance tool that shadows a compiler is a governance tool people uninstall. The npm package is commitcycle; the command is cycle.