Workspace

A Khotan workspace is a monorepo: one GitHub repo per organization, using Bun workspaces and Turborepo. Apps live under apps/deployments/; pipelines live under apps/pipelines/. The repo root holds shared agent skills and instruction files. Per-app guidance lives in each subdirectory's own AGENTS.md / CLAUDE.md. See Concepts for the layout.

Check the checkout

khotan workspace check
khotan workspace check --json

The command fetches origin/main and compares it with HEAD. It updates remote-tracking metadata only. It never merges, rebases, resets, stashes, or changes worktree files.

• synced means HEAD contains the same commits as origin/main.
• ahead means local commits are not on origin/main. The command warns.
• behind means origin/main has commits missing locally. The command blocks.
• diverged means both sides have unique commits. The command blocks.
• unverifiable means the remote is missing or cannot be fetched. The command blocks.
• dirty: true means tracked or untracked worktree changes exist. The command warns unless another state blocks.

In a workspace with .env.khotan.local, catalog write and destructive commands run this check automatically. If the check blocks, update or reconcile the checkout yourself, then run it again. Khotan never changes local Git work.

To recover:

• For behind, review the remote commits and update the checkout. Use git pull --ff-only only when the worktree is safe.
• For diverged, choose and perform the repository's normal merge or rebase workflow.
• For dirty, commit, stash, or keep the changes deliberately.
• For ahead, push the commits when they are ready.
• For unverifiable, restore the origin remote or GitHub access, then retry.

Status

khotan status           # topology: apps, pipelines, databases
khotan status --write   # refresh a committable WORKSPACE.md from live data

Use khotan status to see which subdirectory maps to which app or pipeline, which database it uses, and which repo it deploys from.

Clone

khotan apps get <appId> and khotan pipelines get <pipelineId> return repo.clone (HTTPS, SSH, GitHub CLI) and repo.subdirectory. Databases live in the same repo. See Concepts.

Do not scaffold at the root

Each app lives in its own subdirectory. Do not run app scaffolders (for example khotan-data init) at the repo root. cd into the app's subdirectory first.

Next

See commands for the catalog-derived surface, and output for --json.