# CLI overview



The CLI is the orchestration layer around the [engine](/docs/reference/api/to-artifacts).
It bootstraps projects, manages generator installation, runs the worker, and
reports diagnostics. Every command writes structured JSON output behind `--json`
so agents can consume it programmatically.

## Synopsis [#synopsis]

```
skmtc <command> [args...] [--json] [--no-input]
skmtc -v | --version
```

Install the CLI with `curl -fsSL https://skm.tc/install | sh` (bootstraps Deno
if needed), then invoke it as `skmtc` from any shell. The entry point is
`skmtc/deno/cli/mod.ts`. The top-level `-v` / `--version` flag prints the CLI
version and exits.

## Command list [#command-list]

### Project lifecycle [#project-lifecycle]

| Command   | Purpose                                         | Reference                              |
| --------- | ----------------------------------------------- | -------------------------------------- |
| `init`    | Initialize a new SKMTC workspace                | [init](/docs/reference/cli/init)       |
| `create`  | Scaffold a new local generator from scratch     | [create](/docs/reference/cli/create)   |
| `clone`   | Fork an existing JSR generator into the project | [clone](/docs/reference/cli/clone)     |
| `install` | Add a JSR-hosted generator to the project       | [install](/docs/reference/cli/install) |
| `list`    | Show installed generators in a project          | [list](/docs/reference/cli/list)       |
| `remove`  | Remove a generator from a project               | [remove](/docs/reference/cli/remove)   |

### Generation [#generation]

| Command    | Purpose                                                                                                          | Reference                                |
| ---------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `generate` | Run the engine end-to-end on a project's spec                                                                    | [generate](/docs/reference/cli/generate) |
| `bundle`   | Rebuild the project's `bundle.js` (worker payload)                                                               | [bundle](/docs/reference/cli/bundle)     |
| `clean`    | Delete a project's generated files + manifest, pruning emptied dirs                                              | [clean](/docs/reference/cli/clean)       |
| `dev`      | Watch mode for iterative generator development                                                                   | [dev](/docs/reference/cli/dev)           |
| `describe` | Report a project's preview metadata (supported subjects, enrichment descriptors) by running its bundle read-only | [describe](/docs/reference/cli/describe) |

### Maintenance [#maintenance]

| Command            | Purpose                                                                     | Reference                              |
| ------------------ | --------------------------------------------------------------------------- | -------------------------------------- |
| `migrate variants` | One-shot migration of `client.json` to the variant-aware shape (idempotent) | [migrate](/docs/reference/cli/migrate) |

### Publish [#publish]

| Command   | Purpose                                                                                           | Reference                              |
| --------- | ------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `publish` | Publish a new immutable stack version to skmtc-hub                                                | [publish](/docs/reference/cli/publish) |
| `push`    | Push a project's `client.json` (config + enrichments) to its hub project                          | [push](/docs/reference/cli/push)       |
| `pull`    | Pull a project's config (enrichments + filters) from its hub project into the local `client.json` | [pull](/docs/reference/cli/pull)       |
| `project` | Manage a hub project built from the local setup: `create` a new project, `rm` it                  | [project](/docs/reference/cli/project) |
| `login`   | Validate + store a hub PAT (paste-a-PAT; becomes publish's default credential)                    | [login](/docs/reference/cli/login)     |
| `logout`  | Delete the stored hub credential (idempotent)                                                     | [logout](/docs/reference/cli/logout)   |

### Diagnostics [#diagnostics]

| Command         | Purpose                                             | Reference                                          |
| --------------- | --------------------------------------------------- | -------------------------------------------------- |
| `doctor`        | Diagnose project setup issues                       | [doctor](/docs/reference/cli/doctor)               |
| `agent-context` | Write a structured project state dump for AI agents | [agent-context](/docs/reference/cli/agent-context) |

## Shared flags [#shared-flags]

### `--no-input` [#--no-input]

Disables interactive prompts. Commands that prompt for missing arguments (e.g.,
"which project?", "which generator?") will exit with code 2 instead.

Use in scripts, CI, and agent workflows where TTY-style interaction isn't
possible or desirable.

### `--json` [#--json]

Writes structured JSON to stdout instead of human-readable text.

**Implies `--no-input`** — JSON output is incompatible with interactive
prompting (a prompt would corrupt the JSON stream).

The exact JSON shape is documented per-command. Common fields across commands:

```jsonc
{
  "command": "install",
  "projectName": "my-api",
  // ... command-specific fields
  "verifyWith": "cat .skmtc/my-api/deno.json"
}
```

Many commands include a `verifyWith` field — a follow-up shell command an agent
can run to confirm the operation landed. This is a key affordance for agentic
workflows where the CLI is one tool among many.

## Strict mode [#strict-mode]

When `--no-input` (or `--json`) is set, the CLI runs in **strict mode**:

* Required arguments not provided on the command line cause exit code 2 (rather
  than prompting)
* No interactive disambiguation (e.g., "we found multiple matches, pick one")
* Errors are reported as structured JSON when `--json` is set

This makes the CLI's behavior fully deterministic and scriptable.

## Exit codes [#exit-codes]

The CLI uses a consistent exit-code convention across commands:

| Code | Meaning                                               |
| ---- | ----------------------------------------------------- |
| `0`  | Success                                               |
| `1`  | Operational failure (network, filesystem, validation) |
| `2`  | Invalid invocation (missing args, unknown flags)      |

`doctor` collapses "internal failure" and "a check ran at error severity" onto
exit `1` — it does not use a distinct exit code for diagnostics failures.

Per-command pages document which codes apply.

## Project layout assumed by the CLI [#project-layout-assumed-by-the-cli]

```
workspace-root/
├── deno.json                          # workspace deno.json
├── .skmtc/
│   └── <project>/
│       ├── deno.json                  # per-project generator imports
│       ├── .settings/
│       │   ├── client.json            # per-project settings (source, basePath, enrichments)
│       │   └── manifest.json          # last-run manifest (written by generate)
│       ├── bundle.js                  # generated worker payload
│       └── <generator>/               # cloned or created generator source
│           ├── deno.json
│           ├── mod.ts
│           └── src/
└── (your application code)
```

The `.skmtc/` directory is the CLI's working area. Each subdirectory is a
separate "project" — a logical bundle of generators applied to one spec. Most
workspaces have one project; multi-project workspaces exist when one repo
produces multiple sets of artifacts.

## Configuration files [#configuration-files]

The CLI reads (and sometimes writes) these files:

| File                                       | Purpose                                                         |
| ------------------------------------------ | --------------------------------------------------------------- |
| `deno.json` (workspace root)               | Workspace-level configuration                                   |
| `.skmtc/<project>/deno.json`               | Per-project generator imports                                   |
| `.skmtc/<project>/.settings/client.json`   | Per-project generation settings (source, basePath, enrichments) |
| `.skmtc/<project>/.settings/manifest.json` | Last-run manifest                                               |
| `<generator>/deno.json`                    | Per-generator package metadata                                  |

See
[reference/settings/client-json-schema.md](/docs/reference/settings/client-json-schema)
for the `client.json` schema.

## Command conventions [#command-conventions]

### Project argument [#project-argument]

Most commands take `[project]` as an optional positional argument. Resolution
order:

1. Explicit `[project]` argument
2. Single-project workspace: the project name is inferred
3. Interactive prompt (only if not in strict mode)
4. Strict mode without arg → exit code 2

### Generator argument [#generator-argument]

Generator specifiers can be:

* Bare package names: `@skmtc/gen-zod`
* With semver: `@skmtc/gen-zod@^0.0.55`
* Full JSR specifiers: `jsr:@skmtc/gen-zod@^0.0.55`

The CLI normalizes all three forms.

## Output style [#output-style]

### Human mode (no `--json`) [#human-mode-no---json]

* Colored output to stdout/stderr
* Progress indicators for long-running operations
* Tables for tabular data (e.g., `skmtc list`)

### JSON mode (`--json`) [#json-mode---json]

* Single JSON object to stdout
* Errors go to stderr (also as JSON when `--json` is set)
* No progress indicators

## See also [#see-also]

* skmtc-cli skill — operational digest
  covering the common workflows
* [Reference: client.json schema](/docs/reference/settings/client-json-schema) — the
  per-project settings file
* [The three phases concept](/docs/concepts/the-three-phases) — what
  `generate` orchestrates
* [Clone vs install concept](/docs/concepts/clone-vs-install) — when to use
  `clone` vs `install` vs `create`