You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
config.ts — Local (.draftmark.json) + global (~/.config/draftmark/config.json) config, resolution helpers
37
+
format.ts — ANSI color helpers, label/table/comment formatting, quiet mode
37
38
```
38
39
39
40
Four files. Keep it that way — no unnecessary abstractions.
40
41
41
42
## Architecture Decisions
42
43
43
44
-**Single entry point:** All commands defined in `cli.ts`. Don't split into separate command files unless there are 20+ commands.
44
-
-**Config resolution:** CLI flag > env var > `.draftmark.json`. This order is intentional — flags for one-off overrides, env vars for CI, config file for project context.
45
-
-**Output convention:**`stderr` for status messages (creating, fetching...), `stdout` for data (URLs, JSON, raw markdown). This makes piping work: `dm raw | head`.
46
-
-**No dependencies beyond Commander:** Use built-in `fetch`, `fs`, `path`. Don't add axios, chalk, ora, or similar.
45
+
-**Config resolution:** CLI flag → env var → `.draftmark.json` → global config (`~/.config/draftmark/config.json`). This order is intentional — flags for one-off overrides, env vars for CI, local config for project context, global for account-wide defaults.
46
+
-**Output convention:**`stderr` for status messages (creating, fetching...), `stdout` for data (URLs, JSON, raw markdown). This makes piping work: `dm raw | head`. The `--quiet` flag suppresses all stderr.
47
+
-**Structured errors:** All API errors are normalized to `{ error, code, details }` in `api.ts`. Commands use `fail()` helper for consistent exit codes.
48
+
-**Exit codes:** 0 ok, 1 general error, 2 auth (401/403), 3 not found (404), 4 conflict (409).
49
+
-**No dependencies beyond Commander:** Use built-in `fetch`, `fs`, `path`, `os`, `child_process`. Don't add axios, chalk, ora, or similar.
47
50
-**ANSI colors:** Implemented manually in `format.ts` (6 colors + reset). No chalk dependency.
48
51
49
52
## API Reference
50
53
51
54
The Draftmark API spec lives in the main repo: `draftmark-app/draftmark/openapi.yaml`
52
55
53
-
Base URL: `https://draftmark.app/api/v1` (override with `DM_BASE_URL` env var).
56
+
Base URL: `https://draftmark.app/api/v1` (override with `--base-url` flag or `DM_BASE_URL` env var).
54
57
55
58
### Auth model
56
59
57
60
| Token | Prefix | Use |
58
61
|-------|--------|-----|
59
62
| Doc API Key |`key_`| Read private docs, list comments |
| Base URL |—|`DM_BASE_URL`| Override API endpoint (default: `https://draftmark.app/api/v1`)|
102
+
| Base URL |`--base-url`|`DM_BASE_URL`| Override API endpoint |
63
103
64
-
##`.draftmark.json`
104
+
### Global credentials
65
105
66
-
Created automatically by `dm create`. Stores credentials for the current project:
106
+
```bash
107
+
# Save your account API key globally
108
+
dm login --api-key acct_abc123
67
109
68
-
```json
69
-
[
70
-
{
71
-
"slug": "a1b2c3d4",
72
-
"api_key": "key_...",
73
-
"magic_token": "...",
74
-
"url": "https://draftmark.app/share/a1b2c3d4"
75
-
}
76
-
]
77
-
```
110
+
# Works from any directory now
111
+
dm status abc123
78
112
79
-
Add `.draftmark.json` to your `.gitignore` — it contains secrets.
113
+
# Check what's configured
114
+
dm whoami
115
+
dm config
116
+
```
80
117
81
118
## `dm create` options
82
119
83
120
```
84
-
--private Create as private (magic link only)
121
+
--private Create as private (magic link only, requires --api-key)
85
122
--title <title> Document title
86
123
--expected-reviews <n> Number of reviews before review_complete flag
87
124
--review-deadline <date> ISO date after which feedback is rejected
125
+
--api-key <key> Account API key (required for --private)
126
+
--agent Mark as agent-authored (inherited by comment/review)
127
+
--meta <json> Arbitrary JSON metadata
88
128
--json Output raw JSON response
89
129
```
90
130
91
-
## JSON output
131
+
## Output formats
92
132
93
-
All read commands accept `--json`to output the raw API response:
133
+
Commands that display data support `--json`and `--format`:
94
134
95
135
```bash
136
+
# JSON for programmatic consumption
96
137
dm status --json | jq '.accepting_feedback'
97
138
dm comments --json | jq '.[].body'
139
+
140
+
# Minimal for scripting
141
+
dm status --format minimal # abc123 open public 3c 2r
142
+
dm comments --format minimal # one line per comment
143
+
144
+
# Table (default) for humans
145
+
dm status
146
+
dm comments
98
147
```
99
148
149
+
## `.draftmark.json`
150
+
151
+
Created automatically by `dm create`. Stores credentials for the current project:
152
+
153
+
```json
154
+
[
155
+
{
156
+
"slug": "a1b2c3d4",
157
+
"api_key": "key_...",
158
+
"magic_token": "...",
159
+
"url": "https://draftmark.app/share/a1b2c3d4",
160
+
"author_type": "agent"
161
+
}
162
+
]
163
+
```
164
+
165
+
Add `.draftmark.json` to your `.gitignore` — it contains secrets.
166
+
167
+
The `--agent` flag on `create` stores `author_type: "agent"` here. Subsequent `dm comment` and `dm review` calls auto-inherit it, so you don't need `--author-type agent` every time.
168
+
169
+
## Exit codes
170
+
171
+
| Code | Meaning |
172
+
|------|---------|
173
+
|`0`| Success |
174
+
|`1`| General error (bad input, network failure, server error) |
0 commit comments