> For the complete documentation index, see [llms.txt](https://docs.khotan.com/llms.txt). A markdown version of any page is available at its `index.md` URL. # Projects Use the `khotan` CLI to operate Khotan projects. Add `--json` for machine-readable output; results go to stdout, diagnostics to stderr. ## Commands ### khotan projects attach Usage: `khotan projects attach --resource-kind --resource-id ` Attach an app, pipeline, or database. A resource belongs to at most one project. Arguments & options: - `` — The project id or slug. (required, path) - `--resource-kind` — One of: app, pipeline, database. (required, body) - `--resource-id` — The resource id. (required, body) ### khotan projects create Usage: `khotan projects create --name [--slug ] [--description ]` Create a project and its root goal node. The slug is derived from the name when omitted. Arguments & options: - `--name` — Display name for the project. (required, body) - `--slug` — Stable identifier; derived from the name when omitted. (optional, body) - `--description` — Short summary shown in listings. (optional, body) ### khotan projects delete Usage: `khotan projects delete ` Soft-delete a project and free its slug. The linked tracker project is retained as the record of work done. Arguments & options: - `` — The project id or slug. (required, path) Safety: destructive — prompts for confirmation in a terminal and refuses in non-interactive sessions unless you pass `--yes`. ### khotan projects detach Usage: `khotan projects detach --resource-kind --resource-id ` Remove the membership. The underlying resource is untouched. Arguments & options: - `` — The project id or slug. (required, path) - `--resource-kind` — One of: app, pipeline, database. (required, body) - `--resource-id` — The resource id. (required, body) ### khotan projects get Usage: `khotan projects get ` Fetch one project by id or slug. Arguments & options: - `` — The project id or slug. (required, path) ### khotan projects linear bind Usage: `khotan projects linear bind --linear-project-id ` Bind this project to an existing Linear project. A new project mints its own on first push. Arguments & options: - `` — The project id or slug. (required, path) - `--linear-project-id` — The Linear project id to bind. (required, body) ### khotan projects linear options Usage: `khotan projects linear options [--query ]` List Linear projects this workspace can bind a Khotan project to. Arguments & options: - `--query` — Filter Linear projects by name. (optional, query) ### khotan projects list Usage: `khotan projects list` List the workspace's projects with their current spec revision and resource count. ### khotan projects members Usage: `khotan projects members ` List the apps, pipelines, and databases attached to a project. Arguments & options: - `` — The project id or slug. (required, path) ### khotan projects metrics delete Usage: `khotan projects metrics delete ` Permanently delete a metric and all of its points. Arguments & options: - `` — The project id or slug. (required, path) - `` — The metric key. (required, path) Safety: destructive — prompts for confirmation in a terminal and refuses in non-interactive sessions unless you pass `--yes`. ### khotan projects metrics get Usage: `khotan projects metrics get [--range ]` Read one metric's points over a range, with the range value, the preceding range's value, and the change. Arguments & options: - `` — The project id or slug. (required, path) - `` — The metric key. (required, path) - `--range` — One of: 7d, 30d, 90d. Defaults to 30d. (optional, query) ### khotan projects metrics list Usage: `khotan projects metrics list ` List a project's metrics with their attributes, curation, and last-reported time. Arguments & options: - `` — The project id or slug. (required, path) ### khotan projects metrics report Usage: `khotan projects metrics report --metrics ` Create or update metrics and set their points. Idempotent: points are keyed by bucket, category, or point id, so a retried report never double-counts. Curation made in Khotan is never overwritten. Arguments & options: - `` — The project id or slug. (required, path) - `--metrics` — Array of metrics: { key, shape (series, breakdown, scatter), unit, goal, aggregate, grain, name?, description?, points }. At most 50 metrics and 10,000 points. (required, body) ### khotan projects metrics update Usage: `khotan projects metrics update [--display-name ] [--position ] [--hidden] [--headline]` Change a metric's display name, position, hidden flag, or headline flag. A project has at most three headline metrics. Arguments & options: - `` — The project id or slug. (required, path) - `` — The metric key. (required, path) - `--display-name` — Curated name. Null clears it. (optional, body) - `--position` — Sort position, ascending. (optional, body) - `--hidden` — Hide the metric from readers. Clears headline. (optional, body) - `--headline` — Lead the Metrics tab and the project card. Not available for scatter metrics. (optional, body) ### khotan projects node create Usage: `khotan projects node create --parent-id --title [--body ] [--position ]` Create a child under an existing spec node — a delivery phase under Milestones, or an item under a phase. Arguments & options: - `` — The project id or slug. (required, path) - `--parent-id` — The parent node id. (required, body) - `--title` — Display title for the node. (required, body) - `--body` — Initial body. Empty when omitted. (optional, body) - `--position` — Sibling position. Appended when omitted. (optional, body) ### khotan projects node delete Usage: `khotan projects node delete ` Soft-delete a spec node and its descendants. The goal node cannot be deleted. Arguments & options: - `` — The project id or slug. (required, path) - `` — The spec node id. (required, path) Safety: destructive — prompts for confirmation in a terminal and refuses in non-interactive sessions unless you pass `--yes`. ### khotan projects node update Usage: `khotan projects node update [--title ] [--position ] [--parent-id ] [--start-date ] [--target-date ] [--depends-on-node-id ]` Update a node's title, sibling position, parent, or milestone plan dates. Arguments & options: - `` — The project id or slug. (required, path) - `` — The spec node id. (required, path) - `--title` — Display title for the node. (optional, body) - `--position` — Sibling position. (optional, body) - `--parent-id` — Move the node under this parent. (optional, body) - `--start-date` — Milestone plan start (YYYY-MM-DD). Only valid on a phase. (optional, body) - `--target-date` — Milestone plan target (YYYY-MM-DD). Only valid on a phase. (optional, body) - `--depends-on-node-id` — Milestone this phase waits on. Only valid on a phase. (optional, body) ### khotan projects revision Usage: `khotan projects revision ` Fetch one committed revision with its per-document diff and the cause/effect provenance edges attached to it. Arguments & options: - `` — The project id or slug. (required, path) - `` — The revision number. (required, path) ### khotan projects revisions Usage: `khotan projects revisions [--limit ]` List committed spec revisions newest-first, with actor, timestamp, and change summary. Arguments & options: - `` — The project id or slug. (required, path) - `--limit` — Maximum revisions to return (1-200). (optional, query) ### khotan projects spec Usage: `khotan projects spec [--altitude ]` Read the spec tree at one altitude: high renders the goal, medium adds phases, low adds items and their mirrored tracker issues. Arguments & options: - `` — The project id or slug. (required, path) - `--altitude` — One of: high, medium, low. (optional, query) ### khotan projects update Usage: `khotan projects update [--name ] [--description ] [--lifecycle ] [--tags ]` Update a project's name, description, lifecycle, or tags. Archive with lifecycle archived. An omitted field stays unchanged. Arguments & options: - `` — The project id or slug. (required, path) - `--name` — Display name for the project. (optional, body) - `--description` — Short summary shown in listings. (optional, body) - `--lifecycle` — One of: active, archived. (optional, body) - `--tags` — Full tag list, comma-separated or repeatable; it replaces the stored list, and an empty value clears it. The server lowercases each tag and turns spaces into hyphens. Up to 10 tags of 1-32 lowercase letters, digits, or single hyphens. (optional, body)