@wrktr/cli 0.3.0 → 0.5.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.
Files changed (2) hide show
  1. package/README.md +260 -20
  2. package/package.json +8 -8
package/README.md CHANGED
@@ -1,21 +1,51 @@
1
1
  # @wrktr/cli
2
2
 
3
- Agent-first git on Cloudflare. Each agent gets a branch and a worktree of its own; a daemon commits and pushes
4
- its work as it goes; every push runs your checks and a review agent; and a branch lands when its checks pass, its
5
- review approves and no thread is open.
3
+ **Agent-first git on Cloudflare. Run many coding agents on one repo, and let only the work that passes land.**
6
4
 
7
- The CLI is headless first: everything you can do in the web app that an agent needs, it can do from here, with
8
- `--json` output and no clone required (`--project`).
5
+ ![How wrktr works: each agent gets its own branch and worktree, the daemon commits and pushes, every push runs checks and a review agent, and a branch lands on main once checks pass, the review approves and no thread is open.](https://wrktr.com/readme/flow.svg)
9
6
 
10
- - [Install](#install)
11
- - [Sign in](#sign-in)
7
+ Each agent gets a branch and a worktree of its own. A daemon commits and pushes its work as it goes. Every push runs
8
+ your checks and a review agent. A branch lands on your default branch, as a merge commit made by the server, only
9
+ when its checks pass, its review approves and no thread is open.
10
+
11
+ The CLI is headless first: everything in the web app that an agent needs, with `--json` output and no clone
12
+ required (`--project`).
13
+
14
+ - [Why wrktr](#why-wrktr)
15
+ - [Quickstart](#quickstart)
12
16
  - [The everyday loop](#the-everyday-loop)
17
+ - [For agents](#for-agents)
18
+ - [Command index](#command-index)
13
19
  - [Global flags](#global-flags)
14
- - [Commands](#commands)
20
+ - [Commands](#commands) (the full reference)
15
21
  - [JSON output and exit codes](#json-output-and-exit-codes)
16
22
  - [Environment variables](#environment-variables)
17
23
  - [Files](#files)
18
24
 
25
+ ## Why wrktr
26
+
27
+ Put several agents on one repo and they get in each other's way: they share a checkout, wait on someone to commit
28
+ and push, and leave a person to babysit CI and decide what's safe to merge. wrktr gives each piece of that a home:
29
+
30
+ | Problem | What wrktr does |
31
+ | -------------------------------- | ----------------------------------------------------------------------------------------------------------- |
32
+ | Agents trample one checkout | One branch per agent, each in its own worktree under `.wrktr/worktrees/<branch>`. |
33
+ | Work sits uncommitted | The daemon commits after 30 seconds of quiet, pushes, and merges the default branch back in. |
34
+ | Someone has to watch CI | Every push runs the checks in `wrktr.json`, then a review agent reads the diff and the results. |
35
+ | Feedback gets lost | Review threads and failing checks land in `.wrktr/FEEDBACK.md` in the worktree, where the agent reads them. |
36
+ | Deciding when it's safe to merge | `wrktr land --when-ready`: the server lands the branch once checks, the review and threads allow it. |
37
+
38
+ ## Quickstart
39
+
40
+ ```sh
41
+ npm i -g @wrktr/cli # or, without Node: curl -fsSL https://wrktr.com/install | sh
42
+ wrktr login # approve the sign-in in your browser
43
+ wrktr init # put the repo you're in on wrktr (or: wrktr clone <org>/<project>)
44
+ wrktr daemon install # keep worktrees committed, pushed and up to date, as a login service
45
+ wrktr skill install # teach your coding agents the wrktr way
46
+ wrktr branch new fix-login # then point an agent at .wrktr/worktrees/fix-login
47
+ ```
48
+
19
49
  ## Install
20
50
 
21
51
  ```sh
@@ -48,29 +78,106 @@ A token can't create tokens by itself: only a person signed in to the web app ca
48
78
  ## The everyday loop
49
79
 
50
80
  ```sh
51
- wrktr init # put the repo you're in on wrktr (or: wrktr clone <org>/<project>)
52
- wrktr daemon install # keep worktrees committed, pushed and up to date, as a login service
53
81
  wrktr branch new fix-login # a branch in its own worktree, under .wrktr/worktrees/fix-login
54
82
  cd .wrktr/worktrees/fix-login # ...and just edit: the daemon commits and pushes after a quiet moment
55
83
  wrktr status # checks, the review, open threads, conflicts
84
+ wrktr ci show --wait # wait for the checks; exits 1 unless they passed
56
85
  wrktr feedback show # what the review asked for
57
86
  wrktr feedback reply <id> "Fixed: the token now refreshes before it expires."
58
87
  wrktr land --when-ready # lands by itself once checks, the review and threads allow it
59
88
  ```
60
89
 
90
+ What that looks like on a real branch:
91
+
92
+ ![wrktr status and wrktr ci show in a terminal: checks passed (test, typecheck, lint, format), review approved, no open threads.](https://wrktr.com/readme/status.svg)
93
+
94
+ ## For agents
95
+
96
+ If you're a coding agent working in a wrktr repo, this is the contract. `wrktr skill install` puts the same guidance
97
+ where Claude Code and other agents look for skills, and `wrktr skill show` prints it.
98
+
99
+ **The loop.** Work in the worktree you were given. You don't need `git commit` or `git push`, the daemon does both;
100
+ they're harmless, but don't rewrite pushed history (`rebase`, `push --force`, `commit --amend`).
101
+
102
+ 1. Edit files in `.wrktr/worktrees/<branch>/`. The daemon commits after 30 seconds of quiet and pushes.
103
+ 2. `wrktr ci show --wait` blocks until the head's checks finish, and exits 1 unless they passed.
104
+ 3. Read `.wrktr/FEEDBACK.md` (or `wrktr feedback show`): open review threads and failing checks.
105
+ 4. Fix, then `wrktr feedback reply <id> "<what you did>"`, and `wrktr feedback resolve <id>` when it's done.
106
+ 5. `wrktr land --when-ready`, and the server lands the branch once it's ready.
107
+ 6. If `.wrktr/BEHIND.md` appears, merging the default branch in conflicted: `git fetch wrktr && git merge
108
+ wrktr/<default>`, resolve, commit.
109
+
110
+ **Rules that don't change.**
111
+
112
+ - `--json` prints exactly one JSON value on stdout; a failure prints `{"error": {"tag", "message"}}` on stderr.
113
+ - Exit code `0` means the command did what it was asked; `1` means it didn't. Act on the exit code, not the wording.
114
+ - `--project <org>/<name>` works without a clone; name the branch too (`--branch`, or the branch argument).
115
+ - `WRKTR_TOKEN` signs the CLI in without `login`, for CI and sandboxes.
116
+ - Every command takes `--help`, and every command and flag is in the [reference](#commands) below.
117
+
118
+ ```sh
119
+ wrktr status --branch fix-login --json | jq -r '.review.verdict' # approve, changes or comment
120
+ wrktr status --project nope/nope --branch x --json # exit 1
121
+ # stderr: {"error":{"tag":"ProjectNotFound","message":"Project Not Found"}}
122
+ ```
123
+
124
+ ## Command index
125
+
126
+ Every command at a glance. Each area links to its part of the full [reference](#commands).
127
+
128
+ | Command | What it does |
129
+ | --------------------------------------------------- | ----------------------------------------------------- |
130
+ | **[Account](#account)** | |
131
+ | `wrktr login` | Sign this machine in through the browser |
132
+ | `wrktr whoami` | Who the CLI acts as, and their organizations |
133
+ | `wrktr token ls` / `create` / `revoke` | Access tokens for CI and other agents |
134
+ | **[Projects](#projects)** | |
135
+ | `wrktr init` | Put the repo you're in on wrktr |
136
+ | `wrktr clone <org>/<project>` | Clone a project and register it with the daemon |
137
+ | `wrktr project ls` / `show` / `create` | List, inspect and create projects |
138
+ | **[Organizations](#organizations)** | |
139
+ | `wrktr org ls` / `show` / `create` / `rename` | Your organizations |
140
+ | `wrktr org members` / `add` / `role` / `remove` | The people in one, and their roles |
141
+ | **[Branches](#branches)** | |
142
+ | `wrktr branch new <name>` | A branch in its own worktree |
143
+ | `wrktr branch ls` / `show` / `rm` | List, describe and remove branches |
144
+ | `wrktr branch experiment` / `close` / `reopen` | Keep a branch from landing, or close it |
145
+ | **[Code](#code)** | |
146
+ | `wrktr log [<ref>]` | Commits, newest first |
147
+ | `wrktr diff [<branch>]` | What a branch changes against its base |
148
+ | **[Where a branch stands](#where-a-branch-stands)** | |
149
+ | `wrktr status` | Head, state, checks, review, threads, conflicts |
150
+ | `wrktr feedback show` / `reply` / `resolve` | Work through review threads |
151
+ | **[Reviews](#reviews)** | |
152
+ | `wrktr review ls` / `submit` / `dismiss` | Read, write and set aside reviews |
153
+ | `wrktr review request` | Ask the review agent to review the head now |
154
+ | **[CI](#ci)** | |
155
+ | `wrktr ci show` / `runs` / `log` / `rerun` | Runs, checks, logs, and running them again |
156
+ | **[Landing](#landing)** | |
157
+ | `wrktr land [<branch>]` | Land a branch now, or `--when-ready` |
158
+ | **[Deploys](#deploys)** | |
159
+ | `wrktr env ls` / `runs` / `show` / `logs` | Environments, their runs and step logs |
160
+ | `wrktr env promote` / `rerun` / `cancel` | Ship, retry or stop a deploy |
161
+ | **[Secrets](#secrets)** | |
162
+ | `wrktr secret set` / `ls` / `rm` | The project's deploy secrets (set from stdin) |
163
+ | **[The daemon](#the-daemon)** | |
164
+ | `wrktr daemon install` / `status` / `logs` / ... | The background service that commits, pushes and syncs |
165
+ | **[Agent skill](#agent-skill)** | |
166
+ | `wrktr skill install` / `show` | The skill that teaches agents the wrktr way |
167
+
61
168
  ## Global flags
62
169
 
63
170
  Every command takes these, before or after the subcommand.
64
171
 
65
- | Flag | |
66
- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
67
- | `--project <org>/<name>` | Act on that project on wrktr instead of the clone you're in. No clone is needed, so name the branch too (`--branch`, or the command's branch argument). Commands that act on this machine or your account (`login`, `whoami`, `token`, `init`, `clone`, `branch new`, `branch ls`, `branch rm`, `skill`, `daemon`) refuse it. |
68
- | `--json` | Print the result as JSON on stdout, and a failure as JSON on stderr. See [JSON output](#json-output-and-exit-codes). |
69
- | `--help`, `-h` | Help for any command. |
70
- | `--version`, `-v` | The CLI's version and build. |
71
- | `--log-level <level>` | `all`, `trace`, `debug`, `info`, `warn`, `error`, `fatal` or `none`. |
72
- | `--completions <shell>` | Print a completion script for `bash`, `zsh`, `fish` or `sh`. |
73
- | `--wizard` | Build a command interactively. |
172
+ | Flag | |
173
+ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
174
+ | `--project <org>/<name>` | Act on that project on wrktr instead of the clone you're in. No clone is needed, so name the branch too (`--branch`, or the command's branch argument). Commands that act on this machine or your account (`login`, `whoami`, `token`, `init`, `clone`, `branch new`, `branch rm`, `branch ls` without `--all`, `skill`, `daemon`) refuse it. |
175
+ | `--json` | Print the result as JSON on stdout, and a failure as JSON on stderr. See [JSON output](#json-output-and-exit-codes). |
176
+ | `--help`, `-h` | Help for any command. |
177
+ | `--version`, `-v` | The CLI's version and build. |
178
+ | `--log-level <level>` | `all`, `trace`, `debug`, `info`, `warn`, `error`, `fatal` or `none`. |
179
+ | `--completions <shell>` | Print a completion script for `bash`, `zsh`, `fish` or `sh`. |
180
+ | `--wizard` | Build a command interactively. |
74
181
 
75
182
  ## Commands
76
183
 
@@ -123,6 +230,61 @@ repo with the daemon.
123
230
 
124
231
  Clone a project (into `<directory>`, by default the project's name) and register it with the daemon.
125
232
 
233
+ #### `wrktr project ls [<org>]`
234
+
235
+ Projects, with their default branch and when they last changed: one organization's, or by default every one you
236
+ belong to.
237
+
238
+ #### `wrktr project show [<org>/<name>]`
239
+
240
+ A project: its default branch, last push, git remote and id. Defaults to the clone you're in, or `--project`.
241
+
242
+ #### `wrktr project create <org>/<name>`
243
+
244
+ Create a project on wrktr without a local repo (for one you have locally, use `init`).
245
+
246
+ | Flag | |
247
+ | ---------------------- | ----------------------------------------------------------------------------------- |
248
+ | `--import <url>` | Start it as a copy of an HTTPS git remote, such as a GitHub repo, instead of empty. |
249
+ | `--description <text>` | What the project is. |
250
+
251
+ ### Organizations
252
+
253
+ People are named by email. `<org>` defaults to the organization of the clone you're in, or of `--project`.
254
+
255
+ #### `wrktr org ls`
256
+
257
+ The organizations you belong to, and your role in each.
258
+
259
+ #### `wrktr org show [<org>]`
260
+
261
+ An organization: its name, your role, and its projects.
262
+
263
+ #### `wrktr org create <slug> --name <name>`
264
+
265
+ Create an organization; you become its owner. `<slug>` is its name in URLs and on the CLI.
266
+
267
+ #### `wrktr org rename [<org>] --name <name>`
268
+
269
+ Change an organization's display name (owners only; its slug stays).
270
+
271
+ #### `wrktr org members [<org>]`
272
+
273
+ Its members with their roles, and pending invites.
274
+
275
+ #### `wrktr org add [<org>] <email>`
276
+
277
+ Add someone (owners only). If they have an account they join at once; otherwise they're invited and join when they
278
+ first sign in with that email. `--role <member|owner>` (default `member`).
279
+
280
+ #### `wrktr org role [<org>] <email> <owner|member>`
281
+
282
+ Change a member's role (owners only). An organization always keeps at least one owner.
283
+
284
+ #### `wrktr org remove [<org>] <email>`
285
+
286
+ Remove a member, or cancel a pending invite to that email. Owners remove anyone; you can remove yourself to leave.
287
+
126
288
  ### Branches
127
289
 
128
290
  #### `wrktr branch new <name>`
@@ -138,7 +300,20 @@ reused only if that branch is fully merged.
138
300
 
139
301
  #### `wrktr branch ls`
140
302
 
141
- The branches that have a worktree on this machine.
303
+ The branches that have a worktree on this machine. With `--all`, every branch in progress on wrktr instead (its
304
+ head, state and when it last moved, newest first), from anywhere: it takes `--project`.
305
+
306
+ | Flag | |
307
+ | ---------- | --------------------------------------------------- |
308
+ | `--all` | List the branches on wrktr, not the worktrees here. |
309
+ | `--landed` | With `--all`, include branches that landed. |
310
+ | `--closed` | With `--all`, include branches that were closed. |
311
+
312
+ #### `wrktr branch show [<name>]`
313
+
314
+ What a branch does: the review agent's description of it (a title, a summary, the changes by area, risks and how
315
+ to check it), its head and its state. The description follows the branch as it moves; it says so when it was
316
+ written for an older head.
142
317
 
143
318
  #### `wrktr branch rm <name>`
144
319
 
@@ -162,6 +337,26 @@ reviews stay.
162
337
 
163
338
  Reopen a closed branch.
164
339
 
340
+ ### Code
341
+
342
+ Read a project's history and changes from wrktr, no clone needed.
343
+
344
+ #### `wrktr log [<ref>]`
345
+
346
+ Commits, newest first: short sha, date, author and subject. `<ref>` is a branch or a commit; it defaults to the
347
+ worktree's branch, or the default branch outside a clone. `--limit <n>` for how many (default 20).
348
+
349
+ #### `wrktr diff [<branch>]`
350
+
351
+ What a branch changes against its base: by default a stat, one line per file (`A`dded, `M`odified, `D`eleted,
352
+ `+added -deleted` lines), then the totals.
353
+
354
+ | Flag | |
355
+ | ----------------- | ---------------------------------------------------------- |
356
+ | `--patch`, `-p` | Every file's changes as a unified diff, like `git diff`. |
357
+ | `--file <path>` | Only this file's changes, as a unified diff. |
358
+ | `--base <branch>` | Compare against this branch (default: the default branch). |
359
+
165
360
  ### Where a branch stands
166
361
 
167
362
  #### `wrktr status`
@@ -209,6 +404,42 @@ to the branch's head.
209
404
 
210
405
  Set a review aside so it no longer counts. `<id>` can be the start of an id from `review ls`.
211
406
 
407
+ #### `wrktr review request [<branch>]`
408
+
409
+ Ask the review agent to review the branch's head now, replacing a review of it. It reviews by itself after each
410
+ push once checks pass; this is for a review that failed, or a fresh look at the same head.
411
+
412
+ ### CI
413
+
414
+ Each push runs the checks in `wrktr.json` `ci`. The review agent reads their results, and `land` waits for the
415
+ required ones to pass.
416
+
417
+ #### `wrktr ci show [<run>]`
418
+
419
+ A CI run: each check's state, time and notes (optional, cached, exit code, a retry), and the last lines of the
420
+ ones that failed. Without `<run>`, the branch head's run. `<run>` can be the start of an id from `ci runs`.
421
+
422
+ | Flag | |
423
+ | --------------------- | -------------------------------------------------------------------------------------------------------- |
424
+ | `--branch <name>` | The branch. |
425
+ | `--wait` | Wait until the head's run is over, then exit `1` unless it passed: `wrktr ci show --wait && wrktr land`. |
426
+ | `--timeout <seconds>` | With `--wait`, give up after this long (default 1800), exiting `1`. |
427
+
428
+ #### `wrktr ci runs`
429
+
430
+ The project's CI runs, newest first: status, branch, commit, how long each took. `--branch <name>` for one
431
+ branch's; `--limit <n>` for how many (default 10).
432
+
433
+ #### `wrktr ci log <check>`
434
+
435
+ A check's full log, as stored when it finished (`ci show` prints only the last lines of a failed one). Defaults
436
+ to the branch head's run: `--run <id>` for another, `--branch <name>` for another branch's head.
437
+
438
+ #### `wrktr ci rerun`
439
+
440
+ Run the branch head's checks again, ignoring results reused from an identical tree (for a flaky check, or one
441
+ that depends on something outside the repo). `--branch <name>` for another branch.
442
+
212
443
  ### Landing
213
444
 
214
445
  #### `wrktr land [<branch>]`
@@ -243,6 +474,15 @@ An environment's runs, newest first. `--limit <n>` for how many (default 10).
243
474
  One run: every step (done or not) with its command and state, the last lines of a failed step's log, and the
244
475
  commits it ships.
245
476
 
477
+ #### `wrktr env logs <environment> <run> [<step>]`
478
+
479
+ A run's step logs, in order (or only `<step>`): a finished step's full stored log, and what a running step has
480
+ printed so far. `--json` gives every step's log in one result.
481
+
482
+ | Flag | |
483
+ | ---------------- | ----------------------------------------------------------------------------------------------------------- |
484
+ | `--follow`, `-f` | Keep printing as the run goes, step after step; when it ends, exit `1` unless it passed. Not with `--json`. |
485
+
246
486
  #### `wrktr env promote <environment> [<commit>]`
247
487
 
248
488
  Deploy a commit to a promote environment: by default what its `from` environment has live. The commit must be
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wrktr/cli",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "description": "Agent-first git on Cloudflare: a branch and a worktree per agent, live review, CI and landing.",
5
5
  "homepage": "https://wrktr.com",
6
6
  "bin": {
@@ -10,12 +10,12 @@
10
10
  "bin"
11
11
  ],
12
12
  "optionalDependencies": {
13
- "@wrktr/cli-darwin-arm64": "0.3.0",
14
- "@wrktr/cli-darwin-x64": "0.3.0",
15
- "@wrktr/cli-linux-x64": "0.3.0",
16
- "@wrktr/cli-linux-arm64": "0.3.0",
17
- "@wrktr/cli-linux-x64-musl": "0.3.0",
18
- "@wrktr/cli-linux-arm64-musl": "0.3.0",
19
- "@wrktr/cli-windows-x64": "0.3.0"
13
+ "@wrktr/cli-darwin-arm64": "0.5.0",
14
+ "@wrktr/cli-darwin-x64": "0.5.0",
15
+ "@wrktr/cli-linux-x64": "0.5.0",
16
+ "@wrktr/cli-linux-arm64": "0.5.0",
17
+ "@wrktr/cli-linux-x64-musl": "0.5.0",
18
+ "@wrktr/cli-linux-arm64-musl": "0.5.0",
19
+ "@wrktr/cli-windows-x64": "0.5.0"
20
20
  }
21
21
  }