-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathcli.html
More file actions
371 lines (370 loc) · 13.8 KB
/
cli.html
File metadata and controls
371 lines (370 loc) · 13.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
<!DOCTYPE html>
<html lang="en-GB" dir="ltr">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>CLI reference · Forge</title>
<meta name="description" content="Forge command-line interface: boards, tasks, sync, review, and lint." />
<link rel="icon" type="image/svg+xml" href="favicon.svg" />
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap"
rel="stylesheet"
/>
<link rel="stylesheet" href="assets/site.css?v=3" />
<script>
(function () {
try {
var stored = localStorage.getItem("forge-theme-appearance");
var mode =
stored === "light" || stored === "dark" || stored === "system"
? stored
: "system";
var root = document.documentElement;
if (mode === "light") {
root.classList.add("light");
} else if (mode === "dark") {
root.classList.add("dark");
}
} catch (err) {
/* localStorage unavailable — CSS alone follows prefers-color-scheme */
}
})();
</script>
</head>
<body>
<a href="#main" class="visually-hidden">Skip to content</a>
<header class="site-nav">
<div class="site-nav__inner">
<a class="site-nav__brand" href="index.html">Forge</a>
<nav class="site-nav__links" aria-label="Main navigation">
<a class="site-nav__link" href="index.html">Home</a>
<a class="site-nav__link is-active" href="cli.html">CLI</a>
<a class="site-nav__link" href="app.html">Forge.app</a>
<a class="site-nav__link" href="neovim.html">Neovim</a>
<a class="site-nav__link" href="manual.html">Manual</a>
<a class="site-nav__link" href="privacy.html">Privacy</a>
<a class="site-nav__link" href="readme.html">Readme</a>
<a class="site-nav__link" href="changelog.html">Changelog</a>
<a class="site-nav__link" href="https://github.com/SimonAB/forge" target="_blank" rel="noopener noreferrer">GitHub</a>
</nav>
<div class="site-nav__actions">
<button
type="button"
class="theme-toggle"
id="theme-toggle"
aria-label="Toggle dark mode"
title="Toggle theme"
>
<span class="theme-toggle__icon theme-toggle__icon--sun" aria-hidden="true">
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
<circle cx="12" cy="12" r="4" />
<path d="M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M4.93 19.07l1.41-1.41M17.66 6.34l1.41-1.41" />
</svg>
</span>
<span class="theme-toggle__icon theme-toggle__icon--moon" aria-hidden="true" hidden>
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
<path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
</svg>
</span>
</button>
<a
class="btn btn--alt"
href="https://github.com/SimonAB/forge"
target="_blank"
rel="noopener noreferrer"
>View on GitHub</a
>
</div>
</div>
</header>
<main id="main" class="doc-page">
<article class="doc-content">
<h1>Forge CLI</h1>
<p>The <code>forge</code> command-line tool manages your kanban board from the terminal,
operating directly on your project folders and their <strong>Finder tags</strong>. There are
no remote services; commands read and write only local state.</p>
<h2>Installing the CLI</h2>
<p>Forge bundles the <code>forge</code> binary inside <strong>Forge.app</strong> at <code>Contents/Resources/bin/forge</code>.</p>
<p>To put <code>forge</code> on your <code>$PATH</code>:</p>
<ol>
<li>Open <strong>Forge → Preferences…</strong></li>
<li>Under <strong>Command-line tool (forge)</strong>, click <strong>Install CLI…</strong></li>
<li>Choose:
- <code>~/bin</code> (no admin), or
- <code>/usr/local/bin</code> (admin)</li>
</ol>
<p>To remove it later, use <strong>Uninstall CLI…</strong> in the same Preferences section.</p>
<pre><code>forge <command> [options]
</code></pre>
<h2>Commands at a glance</h2>
<table>
<thead>
<tr>
<th>Command</th>
<th>Purpose</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>forge board</code></td>
<td>Display the kanban board</td>
</tr>
<tr>
<td><code>forge move</code></td>
<td>Move a project between columns</td>
</tr>
<tr>
<td><code>forge project-tag</code></td>
<td>Add, remove, or list meta / assignee Finder tags on a project folder</td>
</tr>
<tr>
<td><code>forge status</code></td>
<td>Summary dashboard of all projects</td>
</tr>
<tr>
<td><code>forge calendar</code> / <code>forge events</code></td>
<td>List upcoming Calendar events (read-only; same command)</td>
</tr>
</tbody>
</table>
<hr />
<h2>forge board</h2>
<p>Display the kanban board showing projects grouped by column.</p>
<pre><code>forge board [--list] [--json] [--column <name>] [--assignee <person>]
</code></pre>
<table>
<thead>
<tr>
<th>Option</th>
<th>Short</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>--list</code></td>
<td><code>-l</code></td>
<td>Compact single-column list instead of the full board</td>
</tr>
<tr>
<td><code>--json</code></td>
<td></td>
<td>Print JSON: <code>board.columns</code> (names and Finder tags), <code>meta_tags</code>, <code>tag_aliases</code>, and each project’s column, tags, assignees, plus <strong>Radar</strong> fields (<code>radarBucket</code>, <code>daysSinceActivity</code>, <code>activityModificationDate</code>, <code>activitySource</code>)</td>
</tr>
<tr>
<td><code>--column</code></td>
<td><code>-c</code></td>
<td>Filter to a specific column (e.g. <code>Active</code>, <code>Write</code>)</td>
</tr>
<tr>
<td><code>--assignee</code></td>
<td><code>-a</code></td>
<td>Filter to projects with this assignee (matches <code>#Person</code> Finder tags)</td>
</tr>
</tbody>
</table>
<p><strong>Examples:</strong></p>
<pre><code class="language-bash">forge board
forge board --list
forge board --json
forge board --json -c Write
</code></pre>
<hr />
<h2>forge move</h2>
<p>Move a project to a different kanban column by changing its Finder tag.</p>
<pre><code>forge move <project> <column>
</code></pre>
<table>
<thead>
<tr>
<th>Argument</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>project</code></td>
<td>Project directory name or unique substring</td>
</tr>
<tr>
<td><code>column</code></td>
<td>Target column name (must match configured column names)</td>
</tr>
</tbody>
</table>
<p><strong>Example:</strong></p>
<pre><code class="language-bash">forge move manuscript Review
</code></pre>
<hr />
<h2>forge project-tag</h2>
<p>Add, remove, or list <strong>Finder tags</strong> on a project directory for <strong>meta</strong> (<code>board.meta_tags</code>)
and <strong>assignee</strong> (<code>#Name</code>) labels. <strong>Kanban column</strong> (workflow) tags are only changed
with <strong><code>forge move</code></strong>.</p>
<pre><code>forge project-tag add <project> <tag> [--force]
forge project-tag remove <project> <tag> [--force]
forge project-tag list <project> [--json]
</code></pre>
<hr />
<h2>forge calendar / forge events</h2>
<p>List upcoming events from <strong>Apple Calendar</strong> (read-only). <strong><code>forge events</code></strong> is an alias
for <strong><code>forge calendar</code></strong> — use whichever you prefer.</p>
<hr />
<h2>forge calendar / forge events</h2>
<p>List upcoming events from <strong>Apple Calendar</strong> (read-only). <strong><code>forge events</code></strong> is an alias for <strong><code>forge calendar</code></strong> — use whichever you prefer. By default the window is the <strong>next 7 days</strong> from the start of today (local timezone).</p>
<p>Uses EventKit on your Mac; nothing is written to Calendar. Optional <code>calendar.include</code> in
<code>config.yaml</code> restricts which calendar <strong>titles</strong> are read (exact match); if
empty or omitted, all event calendars are used.</p>
<pre><code>forge calendar [--days <n>] [--start YYYY-MM-DD] [--json]
forge events [--days <n>] [--start YYYY-MM-DD] [--json]
</code></pre>
<table>
<thead>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>--days</code></td>
<td>Number of calendar days in the window from the anchor day’s midnight (default: <strong>7</strong>)</td>
</tr>
<tr>
<td><code>--start</code></td>
<td>Anchor day (<code>YYYY-MM-DD</code>, local timezone); default: today</td>
</tr>
<tr>
<td><code>--json</code></td>
<td>Print JSON (window bounds + events) for scripting or pasting into a chat</td>
</tr>
</tbody>
</table>
<p><strong>Examples:</strong></p>
<pre><code class="language-bash">forge calendar # Next 7 days (default)
forge events # Same as forge calendar
forge calendar --days 14 --start 2026-04-14
forge calendar --json # Structured output for assistants
</code></pre>
<hr />
<h2>forge move</h2>
<p>Move a project to a different kanban column by changing its Finder tag.</p>
<pre><code>forge move <project> <column>
</code></pre>
<table>
<thead>
<tr>
<th>Argument</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>project</code></td>
<td>Project directory name or unique substring</td>
</tr>
<tr>
<td><code>column</code></td>
<td>Target column name: Plan, Active, Analyse, Write, Review, Shipped, Paused</td>
</tr>
</tbody>
</table>
<p>Both arguments support prefix matching (e.g. <code>act</code> matches <code>Active</code>).</p>
<p><strong>Example:</strong></p>
<pre><code class="language-bash">forge move manuscript Review
</code></pre>
<hr />
<h2>forge project-tag</h2>
<p>Add, remove, or list <strong>Finder tags</strong> on a project directory for <strong>meta</strong> (<code>board.meta_tags</code>) and <strong>assignee</strong> (<code>#Name</code>) labels. <strong>Kanban column</strong> (workflow) tags are only changed with <strong><code>forge move</code></strong> — this command refuses workflow tags so column state stays consistent.</p>
<pre><code>forge project-tag add <project> <tag> [--force]
forge project-tag remove <project> <tag> [--force]
forge project-tag list <project> [--json]
</code></pre>
<table>
<thead>
<tr>
<th>Subcommand</th>
<th>Arguments</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>add</code></td>
<td><code><project></code>, <code><tag></code></td>
<td>Adds the tag if not already present. Without <code>--force</code>, the tag must be listed in <code>board.meta_tags</code> or be a <code>#Person</code> assignee tag.</td>
</tr>
<tr>
<td><code>remove</code></td>
<td><code><project></code>, <code><tag></code></td>
<td>Removes the tag by exact string match. Same validation as <code>add</code>.</td>
</tr>
<tr>
<td><code>list</code></td>
<td><code><project></code></td>
<td>Prints all Finder tags with a <strong>kind</strong> hint: <code>column</code>, <code>meta</code>, <code>assignee</code>, <code>project_scope</code> (if <code>project_tag</code> in config), or <code>other</code>.</td>
</tr>
</tbody>
</table>
<table>
<thead>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>--force</code></td>
<td>On <strong>add</strong> / <strong>remove</strong>, allow tags not in <code>meta_tags</code> and not <code>#…</code> assignee (e.g. legacy labels). <strong>Workflow column tags are still rejected</strong> — use <code>forge move</code>.</td>
</tr>
<tr>
<td><code>--json</code></td>
<td>On <strong>list</strong>, print <code>{ "project", "path", "tags": [{ "name", "kind" }] }</code>.</td>
</tr>
</tbody>
</table>
<p><strong>Examples:</strong></p>
<pre><code class="language-bash">forge project-tag list "Oncho-MIRS-AI_Gates"
forge project-tag add "Oncho-MIRS-AI_Gates" "URGENT ⚠️"
forge project-tag remove Apodemus-DTV_Vaccines "URGENT ⚠️"
forge project-tag list SomeProject --json
</code></pre>
<hr />
<h2>forge status</h2>
<p>Display a colour-coded summary dashboard showing project counts per column,
total projects, active count, and URGENT count.</p>
<pre><code>forge status
</code></pre>
<hr />
<h2>Configuration: project roots</h2>
<p>Set <strong><code>project_roots</code></strong> to a list of paths. Each path’s direct children are
scanned as Forge projects (and filtered by <code>project_tag</code> if set). The first
path is used as the primary workspace (e.g. for resolving the Forge directory
when not found via config location).</p>
<p>When <strong><code>project_tag</code></strong> is set (e.g. <code>"🔥 Forge"</code>), only direct children of each root that have that tag are included. Add multiple roots (e.g. <code>~/Documents/Sanctum</code>) to include more top-level project folders.</p>
<p><strong>Example:</strong></p>
<pre><code class="language-yaml">project_roots:
- ~/Documents/Work/Projects
- ~/Documents/Sanctum
- ~/Documents/Home
project_tag: "🔥 Forge" # only folders with this tag are projects
</code></pre>
<p>Paths support <code>~</code> for the home directory. All commands that list projects
(board, status, etc.) use the union of projects from every listed root.</p>
<p><strong>Legacy:</strong> Configs that only have <code>workspace: <path></code> (no <code>project_roots</code>)
are still read; Forge treats it as <code>project_roots: [<path>]</code>.</p>
</article>
</main>
<footer class="site-footer">
<p>
<a href="index.html">Home</a>
· Source markdown in the
<a href="https://github.com/SimonAB/forge" target="_blank" rel="noopener noreferrer">repository</a>
</p>
<p>Released under the Apache License, Version 2.0.</p>
</footer>
<script src="assets/theme.js?v=3"></script>
</body>
</html>