# Commands

> Every croft 0.2.0 command, its usage and its options, as croft help prints them.

croft 0.2.0 has 22 commands. `croft help <command>` prints the same usage and options in the terminal.

## Every command takes

| Option | What it does |
|---|---|
| `--json` | print one JSON envelope on stdout (progress goes to stderr) |
| `-h, --help` | show help for croft or for a command |
| `-V, --version` | print the croft version |

## confirm

Carry out a destructive action whose impact was printed; only after the user said yes.

```sh
croft confirm <token>
```



## context

The whole project in one payload, for agents (capped at 20 KB).

```sh
croft context [--asset NAME]...
```

| Option | What it does |
|---|---|
| `--asset NAME` | only this asset (repeatable) |

## delete

Move a whole table, or the rows matching --where, to the trash (needs confirmation).

```sh
croft delete <asset> [--where "<expr>"]
```

| Option | What it does |
|---|---|
| `--where <expr>` | delete only the rows where this SQL expression is true |

## describe

One asset: behavior in words, columns, JSON keys, checks, cursor, recent writes, samples.

```sh
croft describe <asset> [--full-values]
```

| Option | What it does |
|---|---|
| `--full-values` | show whole sample values instead of cutting them at 80 characters |

## docs

Offline docs for this version: topics and error codes.

```sh
croft docs [topic|ERROR_CODE] | croft docs --list
```

| Option | What it does |
|---|---|
| `--list` | list every topic and every error code with its category and severity |

## doctor

Check the environment and the project: Bun, DuckDB, the warehouse, storage, Claude files.

```sh
croft doctor
```



## help

List commands, or show one command's usage and options.

```sh
croft help [command]
```



## init

Create a croft project (or data/ inside an existing app); --claude refreshes the Claude files.

```sh
croft init [dir] [--claude] [--with-hook] [--no-install]
```

| Option | What it does |
|---|---|
| `--claude` | only refresh CLAUDE.md's croft block and .claude/skills/croft/SKILL.md |
| `--with-hook` | also add a Claude Code hook that runs croft validate --hook after each edit under assets/ or lib/ (merged into .claude/settings.json) |
| `--no-install` | do not run bun install (the project needs it before its first run) |

## logs

Console output and errors of a step; --runs lists past runs and steps.

```sh
croft logs [asset|run-id] [--failed] [--runs] [--follow] [--lines N]
```

| Option | What it does |
|---|---|
| `--failed` | only failed, crashed or interrupted steps |
| `--runs` | list runs and their steps instead of log text |
| `--follow` | keep printing a running step's output until it ends |
| `--lines N` | how many of the last lines to show (default 200) |

## new

Write a commented, working template for a new asset; --list shows the kinds.

```sh
croft new api|file|sql|transform <name> [--pagination keyset|cursor|link|page] | croft new --list
```

| Option | What it does |
|---|---|
| `--pagination <style>` | for api: keyset (ascending since), cursor (starting_after/has_more), link (Link header) or page (page/per_page) |
| `--list` | list the kinds and pagination styles |

## preview

Build assets in a sandbox and diff them against the live tables; changes nothing real.

```sh
croft preview <asset…> [--rows N] [--rebuild]
```

| Option | What it does |
|---|---|
| `--rows N` | the input rows a TS transform receives, and the rows an ingest fetches (default 1000) |
| `--rebuild` | build from scratch and compare with the live table (finds incremental drift and out-of-band edits) |

## query

One SELECT against the warehouse (read-only, sandboxed; 50 rows unless --limit).

```sh
croft query "<sql>" [--limit N] [--full-values]
```

| Option | What it does |
|---|---|
| `--limit N` | rows to show (default 50) |
| `--full-values` | show whole values instead of cutting them at 80 characters |
| `--preview` | query the preview database that croft preview built (.croft/preview.duckdb) instead of the warehouse |

## rename

Rename an asset: its file, table and state together; lists the references to update.

```sh
croft rename <old> <new>
```



## restore

List the trash, or bring a version of an asset back (needs confirmation).

```sh
croft restore [asset] [--at <time>]
```

| Option | What it does |
|---|---|
| `--at <time>` | the version to restore: its time as croft restore lists it (default: the latest) |

## run

Update assets and the stale transforms downstream (off a terminal the run detaches; croft wait follows it).

```sh
croft run [selector…] [--dry-run] [--only] [--upstream] [--rebuild] [--from <date|ISO|-90d>] [--allow-shrink] [--foreground] [--follow 100s] [--no-wait] [--events]
```

| Option | What it does |
|---|---|
| `--dry-run` | show what would run and why (windows, confirmations) without running; reads only runs.sqlite and never waits |
| `--rebuild` | build the named assets from scratch (an ingest refetches; its table goes to the trash first, after confirmation) |
| `--only` | run only the named assets, not the stale assets downstream of them |
| `--upstream` | also refresh the stale assets the named ones read, first |
| `--from <when>` | backfill a merge ingest from a date, an ISO time or a relative value (-90d, -12h, today) |
| `--allow-shrink` | override SHRINK_GUARD for one replace ingest: the current rows go to the trash first, after confirmation |
| `--foreground` | run in this process even off a terminal (no detaching) |
| `--follow <dur>` | off a terminal: how long to follow the detached run before returning exit 6 (default 100s) |
| `--no-wait` | exit 4 at once when an asset or the database is busy, instead of waiting |
| `--events` | NDJSON progress events on stderr |

## schedule

Turn scheduled runs on or off, pause them, or show when each ingest runs next.

```sh
croft schedule on|off|status|pause [--for 2h] [--no-os-job]
```

| Option | What it does |
|---|---|
| `--for <dur>` | with pause: resume on its own after this long (e.g. 2h, 30m) |
| `--no-os-job` | with on: record scheduling as on without installing the per-user OS job (croft serve ticks instead) |

## secrets

List declared secrets as set or missing; set writes one to .env from a hidden prompt or stdin.

```sh
croft secrets | croft secrets set NAME [--stdin]
```

| Option | What it does |
|---|---|
| `--stdin` | with set: read the value from stdin (for piping from a password manager) |

## serve

A read-only HTTP query server for apps that steps aside for every write, with the scheduler built in.

```sh
croft serve [--host 127.0.0.1] [--port 7447]
```

| Option | What it does |
|---|---|
| `--host <host>` | the address to listen on (default 127.0.0.1; anything else needs an HTTPS proxy in front) |
| `--port <port>` | the port to listen on (default 7447) |

## status

Freshness and health of every asset, and running runs; never waits on the database.

```sh
croft status [--check]
```

| Option | What it does |
|---|---|
| `--check` | exit 1 when anything is failed, crashed, held or stale (a health probe) |

## validate

Static checks and a bind check of every SQL asset (with its output columns); never touches the warehouse.

```sh
croft validate [asset…] [--types] [--hook]
```

| Option | What it does |
|---|---|
| `--types` | also type-check the project's TypeScript with its own tsc --noEmit |
| `--hook` | run as a Claude Code hook: read the edited file from the hook's JSON on stdin, validate that asset and what reads it; errors on stderr with exit 2, warnings to Claude as JSON context on stdout with exit 0, croft's own failures exit 1 |

## version

Print the croft version.

```sh
croft version | croft --version
```



## wait

Block until a detached run ends; exit 6 if it is still running.

```sh
croft wait <run-id> [--timeout 100s]
```

| Option | What it does |
|---|---|
| `--timeout <dur>` | how long to wait before returning exit 6 (default 100s) |
| `--events` | NDJSON progress events on stderr |

Source: https://croft.zabaca.com/docs/reference/cli/