@wrktr/cli 0.4.0 → 0.5.1

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 +208 -12
  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,8 +78,6 @@ 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
@@ -59,6 +87,85 @@ wrktr feedback reply <id> "Fixed: the token now refreshes before it expires."
59
87
  wrktr land --when-ready # lands by itself once checks, the review and threads allow it
60
88
  ```
61
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 credential <org>/<project> get` | git's credential helper, so plain `git pull` works |
138
+ | `wrktr project ls` / `show` / `create` / `visibility` | List, inspect and create projects; make one public |
139
+ | **[Organizations](#organizations)** | |
140
+ | `wrktr org ls` / `show` / `create` / `rename` | Your organizations |
141
+ | `wrktr org members` / `add` / `role` / `remove` | The people in one, and their roles |
142
+ | **[Branches](#branches)** | |
143
+ | `wrktr branch new <name>` | A branch in its own worktree |
144
+ | `wrktr branch ls` / `show` / `rm` | List, describe and remove branches |
145
+ | `wrktr branch experiment` / `close` / `reopen` | Keep a branch from landing, or close it |
146
+ | **[Code](#code)** | |
147
+ | `wrktr log [<ref>]` | Commits, newest first |
148
+ | `wrktr diff [<branch>]` | What a branch changes against its base |
149
+ | **[Where a branch stands](#where-a-branch-stands)** | |
150
+ | `wrktr status` | Head, state, checks, review, threads, conflicts |
151
+ | `wrktr feedback show` / `reply` / `resolve` | Work through review threads |
152
+ | **[Reviews](#reviews)** | |
153
+ | `wrktr review ls` / `submit` / `dismiss` | Read, write and set aside reviews |
154
+ | `wrktr review request` | Ask the review agent to review the head now |
155
+ | **[CI](#ci)** | |
156
+ | `wrktr ci show` / `runs` / `log` / `rerun` | Runs, checks, logs, and running them again |
157
+ | **[Landing](#landing)** | |
158
+ | `wrktr land [<branch>]` | Land a branch now, or `--when-ready` |
159
+ | **[Deploys](#deploys)** | |
160
+ | `wrktr env ls` / `runs` / `show` / `logs` | Environments, their runs and step logs |
161
+ | `wrktr env promote` / `rerun` / `cancel` | Ship, retry or stop a deploy |
162
+ | **[Secrets](#secrets)** | |
163
+ | `wrktr secret set` / `ls` / `rm` | The project's deploy secrets (set from stdin) |
164
+ | **[The daemon](#the-daemon)** | |
165
+ | `wrktr daemon install` / `status` / `logs` / ... | The background service that commits, pushes and syncs |
166
+ | **[Agent skill](#agent-skill)** | |
167
+ | `wrktr skill install` / `show` | The skill that teaches agents the wrktr way |
168
+
62
169
  ## Global flags
63
170
 
64
171
  Every command takes these, before or after the subcommand.
@@ -113,7 +220,8 @@ Revoke a token. Whatever uses it stops working at once. `<id>` can be the start
113
220
  #### `wrktr init`
114
221
 
115
222
  Create a wrktr project for the repo you're in and push it, or link the repo to an existing one. It registers the
116
- repo with the daemon.
223
+ repo with the daemon and sets up [`wrktr credential`](#wrktr-credential-orgproject-get) so plain git works with
224
+ the remote.
117
225
 
118
226
  | Flag | |
119
227
  | --------------- | -------------------------------------------------------------------------------- |
@@ -122,7 +230,86 @@ repo with the daemon.
122
230
 
123
231
  #### `wrktr clone <org>/<project> [<directory>]`
124
232
 
125
- Clone a project (into `<directory>`, by default the project's name) and register it with the daemon.
233
+ Clone a project (into `<directory>`, by default the project's name) and register it with the daemon. Plain git
234
+ works in it from then on (see `wrktr credential`).
235
+
236
+ #### `wrktr credential <org>/<project> get`
237
+
238
+ git's credential helper for a wrktr remote: you don't run it, git does. The remote only takes short-lived tokens,
239
+ so instead of a saved password, `init` and `clone` set this in the repo's `.git/config`, for the remote's URL only:
240
+
241
+ ```ini
242
+ [credential "https://…/git/<namespace>/<project>.git"]
243
+ helper =
244
+ helper = !wrktr credential <org>/<project>
245
+ ```
246
+
247
+ Then `git pull`, `git fetch` and `git push` (and your editor's git) work as they do anywhere else: each time git
248
+ needs to authenticate, it gets a fresh token minted for you. The empty `helper =` keeps a global helper (such as
249
+ the macOS keychain) from storing a token that's about to expire. `store` and `erase` do nothing. Repos set up
250
+ before this get it the next time the daemon starts. When you're not signed in, git fails with the reason instead of
251
+ asking for a password.
252
+
253
+ #### `wrktr project ls [<org>]`
254
+
255
+ Projects, with their default branch and when they last changed: one organization's, or by default every one you
256
+ belong to.
257
+
258
+ #### `wrktr project show [<org>/<name>]`
259
+
260
+ A project: who can see it, its default branch, last push, git remote and id. Defaults to the clone you're in, or `--project`.
261
+
262
+ #### `wrktr project create <org>/<name>`
263
+
264
+ Create a project on wrktr without a local repo (for one you have locally, use `init`).
265
+
266
+ | Flag | |
267
+ | ---------------------- | ----------------------------------------------------------------------------------- |
268
+ | `--import <url>` | Start it as a copy of an HTTPS git remote, such as a GitHub repo, instead of empty. |
269
+ | `--description <text>` | What the project is. |
270
+
271
+ #### `wrktr project visibility public|private`
272
+
273
+ Make the project public, so anyone can read its code, history, branches, reviews and CI, signed in or not, or private
274
+ again (its organization's members only). Owners only. Only members can ever change a project; someone outside it who
275
+ runs `wrktr clone` gets a read-only copy that `git pull` keeps current and the daemon leaves alone.
276
+
277
+ ### Organizations
278
+
279
+ People are named by email. `<org>` defaults to the organization of the clone you're in, or of `--project`.
280
+
281
+ #### `wrktr org ls`
282
+
283
+ The organizations you belong to, and your role in each.
284
+
285
+ #### `wrktr org show [<org>]`
286
+
287
+ An organization: its name, your role, and its projects.
288
+
289
+ #### `wrktr org create <slug> --name <name>`
290
+
291
+ Create an organization; you become its owner. `<slug>` is its name in URLs and on the CLI.
292
+
293
+ #### `wrktr org rename [<org>] --name <name>`
294
+
295
+ Change an organization's display name (owners only; its slug stays).
296
+
297
+ #### `wrktr org members [<org>]`
298
+
299
+ Its members with their roles, and pending invites.
300
+
301
+ #### `wrktr org add [<org>] <email>`
302
+
303
+ Add someone (owners only). If they have an account they join at once; otherwise they're invited and join when they
304
+ first sign in with that email. `--role <member|owner>` (default `member`).
305
+
306
+ #### `wrktr org role [<org>] <email> <owner|member>`
307
+
308
+ Change a member's role (owners only). An organization always keeps at least one owner.
309
+
310
+ #### `wrktr org remove [<org>] <email>`
311
+
312
+ Remove a member, or cancel a pending invite to that email. Owners remove anyone; you can remove yourself to leave.
126
313
 
127
314
  ### Branches
128
315
 
@@ -313,6 +500,15 @@ An environment's runs, newest first. `--limit <n>` for how many (default 10).
313
500
  One run: every step (done or not) with its command and state, the last lines of a failed step's log, and the
314
501
  commits it ships.
315
502
 
503
+ #### `wrktr env logs <environment> <run> [<step>]`
504
+
505
+ A run's step logs, in order (or only `<step>`): a finished step's full stored log, and what a running step has
506
+ printed so far. `--json` gives every step's log in one result.
507
+
508
+ | Flag | |
509
+ | ---------------- | ----------------------------------------------------------------------------------------------------------- |
510
+ | `--follow`, `-f` | Keep printing as the run goes, step after step; when it ends, exit `1` unless it passed. Not with `--json`. |
511
+
316
512
  #### `wrktr env promote <environment> [<commit>]`
317
513
 
318
514
  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.4.0",
3
+ "version": "0.5.1",
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.4.0",
14
- "@wrktr/cli-darwin-x64": "0.4.0",
15
- "@wrktr/cli-linux-x64": "0.4.0",
16
- "@wrktr/cli-linux-arm64": "0.4.0",
17
- "@wrktr/cli-linux-x64-musl": "0.4.0",
18
- "@wrktr/cli-linux-arm64-musl": "0.4.0",
19
- "@wrktr/cli-windows-x64": "0.4.0"
13
+ "@wrktr/cli-darwin-arm64": "0.5.1",
14
+ "@wrktr/cli-darwin-x64": "0.5.1",
15
+ "@wrktr/cli-linux-x64": "0.5.1",
16
+ "@wrktr/cli-linux-arm64": "0.5.1",
17
+ "@wrktr/cli-linux-x64-musl": "0.5.1",
18
+ "@wrktr/cli-linux-arm64-musl": "0.5.1",
19
+ "@wrktr/cli-windows-x64": "0.5.1"
20
20
  }
21
21
  }