@khotan/cli 0.12.0 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +33 -47
- package/dist/khotan.js +451 -17581
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -24,32 +24,6 @@ bun run khotan -- --help # via the root script
|
|
|
24
24
|
bun packages/khotan-cli/src/bin/khotan.ts --help # directly
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
-
## Scaffold a workspace
|
|
28
|
-
|
|
29
|
-
`khotan init` writes Khotan agent integration into the current directory so your
|
|
30
|
-
own agents (Cursor, Devin, …) can drive setup. It is non-destructive and
|
|
31
|
-
re-runnable, and never writes secrets.
|
|
32
|
-
|
|
33
|
-
```bash
|
|
34
|
-
khotan init # Cursor: .cursor/rules/khotan.mdc
|
|
35
|
-
khotan init --client generic # khotan-agents.md
|
|
36
|
-
khotan init --force # regenerate managed assets, overwriting edits
|
|
37
|
-
khotan init --json # machine-readable summary on stdout
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
It writes agent guidance for using the CLI. Authenticate separately with
|
|
41
|
-
`khotan auth set-key` or environment variables — never commit a key.
|
|
42
|
-
|
|
43
|
-
`init` also installs catalog-derived agent **skills** for using the CLI into
|
|
44
|
-
`.cursor/skills/`, `.agents/skills/`, and `.claude/skills/` (regardless of
|
|
45
|
-
`--client`): an overview `khotan` skill plus one per command domain
|
|
46
|
-
(`khotan-apps`, `khotan-databases`, …). The skills are generated from the same
|
|
47
|
-
capability catalog that drives the commands and `khotan help`, so they can
|
|
48
|
-
never drift. They are **managed assets**: every `khotan init` run regenerates
|
|
49
|
-
them in place (no `--force` needed), so re-running `init` is how a workspace
|
|
50
|
-
picks up new CLI commands — like the `databases branches` group. Your
|
|
51
|
-
hand-authored rule/guide stays non-destructive (preserved unless `--force`).
|
|
52
|
-
|
|
53
27
|
## Authentication & profiles
|
|
54
28
|
|
|
55
29
|
The CLI authenticates with an organization-scoped **API key**. Credentials are
|
|
@@ -92,12 +66,12 @@ khotan apps list --profile staging # one-off override
|
|
|
92
66
|
Environment variables take precedence over stored profile values, so no on-disk
|
|
93
67
|
state is needed in CI or sandboxes:
|
|
94
68
|
|
|
95
|
-
| Variable
|
|
96
|
-
|
|
|
97
|
-
| `KHOTAN_API_URL`
|
|
98
|
-
| `KHOTAN_API_KEY`
|
|
99
|
-
| `KHOTAN_PROFILE`
|
|
100
|
-
| `KHOTAN_ORG_ID`
|
|
69
|
+
| Variable | Purpose |
|
|
70
|
+
| ---------------- | ---------------------------------------------------------------------------------------------- |
|
|
71
|
+
| `KHOTAN_API_URL` | API origin (e.g. `https://app.example.com`) |
|
|
72
|
+
| `KHOTAN_API_KEY` | Organization-scoped API key |
|
|
73
|
+
| `KHOTAN_PROFILE` | Select a stored profile by name |
|
|
74
|
+
| `KHOTAN_ORG_ID` | Expected org id; the CLI asserts `whoami.organizationId` matches it and fails closed otherwise |
|
|
101
75
|
|
|
102
76
|
```bash
|
|
103
77
|
export KHOTAN_API_URL=https://app.example.com
|
|
@@ -105,17 +79,17 @@ export KHOTAN_API_KEY=khk_live_...
|
|
|
105
79
|
khotan apps list --json | jq '.apps[].id'
|
|
106
80
|
```
|
|
107
81
|
|
|
108
|
-
### Repo-local org isolation (
|
|
82
|
+
### Repo-local org isolation (`.env.khotan.local`)
|
|
109
83
|
|
|
110
|
-
When an
|
|
84
|
+
When an `.env.khotan.local` file sits at (or above) the working directory, the CLI
|
|
111
85
|
auto-loads its `KHOTAN_*` values so every command is scoped to that repo's
|
|
112
86
|
organization — never a stray machine-global profile from another customer. The
|
|
113
87
|
file is authoritative: its values win over shell-exported `KHOTAN_*`, which win
|
|
114
88
|
over the stored profile, and CLI flags win over everything (`flag >
|
|
115
|
-
env.khotan.local > shell env > profile`).
|
|
89
|
+
.env.khotan.local > shell env > profile`).
|
|
116
90
|
|
|
117
91
|
```bash
|
|
118
|
-
# env.khotan.local (git-ignored; never commit secrets)
|
|
92
|
+
# .env.khotan.local (git-ignored; never commit secrets)
|
|
119
93
|
KHOTAN_API_URL='https://<customer>.khotan.com'
|
|
120
94
|
KHOTAN_API_KEY='<org-scoped key>'
|
|
121
95
|
KHOTAN_ORG_ID='<org id>'
|
|
@@ -126,23 +100,35 @@ When `KHOTAN_ORG_ID` (or `--assert-org <id>`) is set, every operation verifies
|
|
|
126
100
|
mismatch (`error [org_mismatch]`). With no expected org id set, behavior is
|
|
127
101
|
unchanged.
|
|
128
102
|
|
|
103
|
+
## Workspace freshness
|
|
104
|
+
|
|
105
|
+
Run `khotan workspace check --json` to fetch and compare `origin/main` with the
|
|
106
|
+
current checkout. It reports the relation, commit counts, dirty state, and
|
|
107
|
+
whether a mutation must stop.
|
|
108
|
+
|
|
109
|
+
The CLI blocks catalog write and destructive commands from a Khotan workspace
|
|
110
|
+
that is behind, diverged, or unverifiable. A dirty or ahead checkout produces a
|
|
111
|
+
warning. The check updates remote-tracking metadata only; it never changes
|
|
112
|
+
local commits, the index, or worktree files.
|
|
113
|
+
|
|
129
114
|
## Command surface
|
|
130
115
|
|
|
131
116
|
Commands are grouped by domain and derived from the capability catalog, so the
|
|
132
117
|
documented surface and the executable surface cannot drift. Run `khotan help` or
|
|
133
118
|
`khotan <command> --help` for details.
|
|
134
119
|
|
|
135
|
-
| Domain
|
|
136
|
-
|
|
|
137
|
-
|
|
|
138
|
-
|
|
|
139
|
-
|
|
|
140
|
-
|
|
|
141
|
-
|
|
|
142
|
-
|
|
|
143
|
-
|
|
|
144
|
-
| Context
|
|
145
|
-
| Context
|
|
120
|
+
| Domain | Examples |
|
|
121
|
+
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
122
|
+
| Workspace | `workspace check`, `status`, `status --write` |
|
|
123
|
+
| Apps | `apps list`, `apps get <id>`, `apps create --name web --env KEY=VALUE`, `apps delete <id>`, `apps redeploy <id>` |
|
|
124
|
+
| App env | `apps env list <id>`, `apps env set <id> <KEY> --value V`, `apps env reveal <id> <KEY>`, `apps env unset <id> <KEY>`, `apps env bulk-set <id> --var A=1 --var B=2` |
|
|
125
|
+
| Pipelines | same shape as apps under `pipelines …` |
|
|
126
|
+
| Databases | `databases list`, `databases create --name db`, `databases connection <id>`, `databases rotate-credentials <id>`, `databases delete <id>` |
|
|
127
|
+
| Files | `files list`, `files get <id>`, `files upload <path>`, `files download <id> --output <path>`, `files download-url <id>`, `files preview-url <id>`, `files update <id> --name new.txt`, `files delete <id>` |
|
|
128
|
+
| Folders | `folders list`, `folders create --name docs`, `folders rename <id> --name new`, `folders delete <id>` |
|
|
129
|
+
| Context | `context list`, `context get <slug>`, `context raw <slug>`, `context create --title T --kind knowledge --content '...' --folder-id <id>`, `context update <slug> --expected-revision 3 --content '...' --folder-id <id>`, `context delete <slug>` |
|
|
130
|
+
| Context folders | `context folders list`, `context folders create --name docs --parent-id <id>`, `context folders update <id> --name new --parent-id <id>`, `context folders delete <id> --recursive` |
|
|
131
|
+
| Context revisions | `context revisions list <slug>`, `context revisions get <slug> <revision>`, `context revisions restore <slug> <revision>` |
|
|
146
132
|
|
|
147
133
|
### Output modes
|
|
148
134
|
|