> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inklyai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI commands

> Command reference for the inkly binary: init, add, dev, validate, login, capture, snapshot, and more.

Every command runs as `inkly <command>`. Run `inkly help` for the full list, or `inkly <command> --help` for one command's usage. `inkly version` and `inkly --version` print the CLI version.

Capture and publishing commands are summarized here. For task guides, see [Agentic capture](/cli/capture), [Publish a demo](/cli/publish-a-snapshot), and [Sync assets](/cli/sync-assets).

## `inkly init`

Scaffold a new hub directory.

```bash theme={null}
inkly init <name> [--layout <layout>]
```

* `<name>` is the folder name for the new hub. It must be a valid slug, and the command refuses to overwrite an existing directory.
* `--layout <layout>` writes a hub-index layout to `inkly.json`. One of `sidebar` or `tabs`.

The scaffold is fetched from the current runtime skeleton. It writes `README.md`, `CLAUDE.md`, `.gitignore`, `inkly.json`, and a starter demo at `demos/getting-started/demo.config.json`.

```bash theme={null}
inkly init acme-demo-hub
```

## `inkly add`

Add or import a demo in the current hub.

```bash theme={null}
inkly add <name> [--collection <name>]
inkly add [<name>] --from <dir> [--collection <name>]
```

* `<name>` is the folder name (slug) for the new demo. The command assigns the demo a stable id inside `demo.config.json`.
* `--from <dir>` imports an existing demo folder, such as an `inkly capture stop` export. The source folder must contain `demo.config.json`.
* `--collection <name>` adds the demo to that collection in `inkly.json`, creating the collection if it does not exist.

Behavior:

* The command walks upward from the current directory to find `inkly.json`. It fails if you are not inside a hub.
* It validates the slug before writing and refuses to overwrite an existing demo folder.
* A scaffolded demo joins no collection unless you pass `--collection`.
* An imported demo keeps its existing id when valid, copies `assets.json`, `public/`, and `snapshots/`, and joins the hub's only collection automatically when the hub has exactly one collection.

```bash theme={null}
inkly add onboarding-tour
inkly add pricing-walkthrough --collection "Sales"
inkly add onboarding-tour --from ./out/onboarding-tour
```

## `inkly demo`

Alias of `inkly add`. Same arguments and behavior.

```bash theme={null}
inkly demo <slug> [--collection <name>]
inkly demo [<slug>] --from <dir> [--collection <name>]
```

## `inkly dev`

Start the local preview server for a hub or an exported demo folder.

```bash theme={null}
inkly dev [<path>] [--port <n>]
```

* `<path>` can be a hub root or a bare demo folder that contains `demo.config.json`. It defaults to the current directory.
* `--port <n>` (alias `-p`) sets the preferred port. The default is `3000`; if that port is taken, the CLI tries the next available port. Must be an integer from 1 to 65535.

The server watches `inkly.json`, demo config files, and asset files. When you pass a bare demo folder, the CLI wraps it in a temporary hub for preview. Press `Ctrl+C` to stop it. See [Preview locally](/cli/preview-locally).

## `inkly validate`

Validate the hub and every demo file.

```bash theme={null}
inkly validate [--json] [--strict]
```

* `--json` prints a machine-readable result.
* `--strict` treats warnings as failures.

The command checks the hub theme, each demo's slug and theme preset, `asset:` references against `assets.json`, duplicate demo ids, and collection references. It exits non-zero when there are errors (or, with `--strict`, any warnings). Each issue prints as `ERROR <file>: <message>` or `WARNING <file>: <message>`.

## `inkly lock`

Generate or verify `inkly.lock`.

```bash theme={null}
inkly lock [--json] [--local <path>]
inkly lock --check [--json] [--local <path>]
```

* `--check` verifies that `inkly.lock` matches the runtime manifest without changing files. It exits non-zero on drift.
* `--local <path>` sources the runtime manifest from a local `manifest.json`, `dist/` directory, or runtime package root.
* `--json` prints machine-readable output.

Use `inkly lock --check` in CI when you want runtime drift to fail the build.

## `inkly status`

Show local auth and hub status.

```bash theme={null}
inkly status [--json]
```

Prints the config file path, the detected hub root (or that you are not inside a hub), the configured API base, whether a login token is saved, and an online check of that token. Exits non-zero when no token is configured.

## `inkly login`

Connect the CLI to the hosted Inkly app.

```bash theme={null}
inkly login [--no-open]
inkly login --token <token>
```

* `--no-open` prints the grant URL instead of opening a browser.
* `--token <token>` saves an existing API token directly, skipping the browser flow. Useful for automation.

By default `inkly login` opens a browser, completes a pairing exchange, and writes the resulting token to the CLI config file. The platform origin is fixed on the command line.

## `inkly logout`

Remove saved platform credentials.

```bash theme={null}
inkly logout
```

Clears the CLI config file.

## `inkly doctor`

Run local diagnostics.

```bash theme={null}
inkly doctor [--json]
```

Reports the CLI version, Node.js version, hub root, login status, validation results, and local cache state.

## `inkly version`

Print the CLI version.

```bash theme={null}
inkly version
inkly --version
```

## `inkly update`

Update the globally installed CLI.

```bash theme={null}
inkly update [--dry-run]
```

* `--dry-run` prints the install command without running it.

The command runs a global install of `@inkly-org/cli@latest`.

## Capture and publishing commands

These commands are summarized here. See the task pages for goal-specific workflows.

* **`inkly capture <command>`** — capture an image or video walkthrough for an agent. See [Agentic capture](/cli/capture).
* **`inkly capture-html <command>`** — capture a self-contained HTML walkthrough. See [Agentic capture](/cli/capture).
* **`inkly sync [--demo <slug>] [--dry-run] [--json]`** — upload local capture blobs to Inkly storage as an optional repo cleanup step. See [Sync assets](/cli/sync-assets).
* **`inkly snapshot <demo-path> [--demo <slug>] [--json]`** — publish a standalone demo at a `/p/<id>` URL. See [Publish a demo](/cli/publish-a-snapshot).
* **`inkly lock [--check] [--local <path>] [--json]`** — generate or verify `inkly.lock`, pinning the runtime version.
* **`inkly skills install`** — install or refresh the Inkly CLI skill for local agents. See [Skills for agents](/cli/skills).

## Troubleshooting

### Invalid demo config

`inkly dev` skips a demo whose `demo.config.json` is not valid JSON or fails validation. The rest of the hub still renders. To see every problem at once and fail on errors, run `inkly validate`. An invalid `inkly.json` stops the dev server from starting.

### Not inside a hub

`inkly add`, `inkly sync`, and `inkly lock` must run inside a hub. They walk upward from the current directory looking for `inkly.json`. If none is found, run `inkly init <name>` first, or `cd` into a directory that contains `inkly.json`.

`inkly dev` and `inkly snapshot` can also accept a bare exported demo folder that contains `demo.config.json`.