this repo has no description
CLI docs, needs some iteration, but covers the commands
+235
+235
docs/cli.md
+235
docs/cli.md
···
1
+
# @sitebase/cli
2
+
3
+
The sitebase CLI is a tool for managing your standard.site data from the command line.
4
+
5
+
## Installation
6
+
7
+
```bash
8
+
# From the monorepo
9
+
bun install
10
+
bun run --filter @sitebase/cli build
11
+
12
+
# Link globally (optional)
13
+
bun link
14
+
```
15
+
16
+
## Setting the target publication
17
+
18
+
All commands except `auth *` and `pub list` require a target publication.
19
+
20
+
The target is determined from these sources, in order of precedence:
21
+
22
+
1. `--pub-id <rkey>` argument passed to the command
23
+
2. `.sitebase.json` file in the current directory with a `publicationId` property
24
+
3. `SITEBASE_PUB_ID` environment variable
25
+
26
+
The value is the **rkey** of the publication record (the last segment of the AT URI).
27
+
28
+
## Commands
29
+
30
+
### Auth
31
+
32
+
#### `auth login <handle>`
33
+
34
+
Logs in to an ATProto account via OAuth.
35
+
36
+
- Launches a temporary local HTTP server to handle the OAuth callback
37
+
- Opens your browser to the authorization page
38
+
- Requests the [standard.site auth bundle](https://pdsls.dev/at://did:plc:re3ebnp5v7ffagz6rb6xfei4/com.atproto.lexicon.schema/site.standard.authFull)
39
+
- Stores session data in `$HOME/.sitebase/session.json`
40
+
41
+
```bash
42
+
sitebase auth login <atproto-handle>
43
+
```
44
+
45
+
#### `auth logout`
46
+
47
+
Clears the stored session data.
48
+
49
+
```bash
50
+
sitebase auth logout
51
+
```
52
+
53
+
### Publication
54
+
55
+
#### `pub list`
56
+
57
+
Lists all publications in the authenticated account's PDS.
58
+
59
+
Does not require a target publication.
60
+
61
+
```bash
62
+
sitebase pub list
63
+
```
64
+
65
+
#### `pub set`
66
+
67
+
Interactively select a publication from your account to set as the target.
68
+
69
+
Writes the selection to `.sitebase.json` in the current directory.
70
+
71
+
```bash
72
+
sitebase pub set
73
+
```
74
+
75
+
#### `pub view`
76
+
77
+
Displays information about the target publication (name, URL, description, AT URI).
78
+
79
+
```bash
80
+
sitebase pub view # reads from SITEBASE_PUB_ID or .sitebase.json
81
+
sitebase pub view --pub-id my-blog
82
+
```
83
+
84
+
#### `pub edit`
85
+
86
+
Opens the publication metadata in `$EDITOR` for editing.
87
+
88
+
The publication data is presented as YAML. Save and close the editor to write changes back to the PDS.
89
+
90
+
```bash
91
+
sitebase pub edit
92
+
```
93
+
94
+
#### `pub export`
95
+
96
+
Exports all documents from the target publication to local files.
97
+
98
+
Uses a `sitebase.config.ts` configuration file. See [export.md](./export.md) for config format.
99
+
100
+
```bash
101
+
# Auto-discover sitebase.config.ts in current directory
102
+
sitebase pub export
103
+
104
+
# Specify config file
105
+
sitebase pub export --config ./my-config.ts
106
+
```
107
+
108
+
**Options:**
109
+
110
+
| Option | Description |
111
+
|--------|-------------|
112
+
| `-c, --config <file>` | Path to config file (auto-discovers `sitebase.config.ts` if not specified) |
113
+
| `--init` | Create a starter `sitebase.config.ts` and `templates/post.hbs` in the current directory |
114
+
115
+
```bash
116
+
# Initialize export config
117
+
sitebase pub export --init
118
+
```
119
+
120
+
### Documents
121
+
122
+
#### `doc list`
123
+
124
+
Lists all documents in the target publication.
125
+
126
+
```bash
127
+
sitebase doc list
128
+
sitebase doc list --tag post # Filter by tag
129
+
sitebase doc list --tag draft # Show drafts
130
+
```
131
+
132
+
#### `doc view <rkey>`
133
+
134
+
Displays a document's metadata and content preview.
135
+
136
+
```bash
137
+
sitebase doc view abc123
138
+
```
139
+
140
+
#### `doc edit <rkey>`
141
+
142
+
Opens a document in `$EDITOR` for editing.
143
+
144
+
The document is presented as a markdown file with YAML frontmatter (metadata in frontmatter, content in body). Save and close the editor to write changes back to the PDS.
145
+
146
+
**Content type restriction:** Only documents with `pub.sitebase.content.*` types can be edited. Documents with other content types (e.g., pckt.blog blocks) will show an error. Use `doc view` to inspect these documents instead.
147
+
148
+
```bash
149
+
sitebase doc edit abc123
150
+
```
151
+
152
+
#### `doc import <file>`
153
+
154
+
Creates a new document in the target publication from a local file.
155
+
156
+
The file should be markdown with YAML frontmatter containing at least a `title` field.
157
+
158
+
```bash
159
+
sitebase doc import ./my-post.md
160
+
sitebase doc import ./my-post.md --tag post --tag featured
161
+
```
162
+
163
+
#### `doc export <rkey>`
164
+
165
+
Exports a single document to a local file or stdout.
166
+
167
+
Unlike `pub export`, this command does NOT use the config file. Instead, options are provided via command line arguments.
168
+
169
+
```bash
170
+
# Output raw markdown to stdout
171
+
sitebase doc export abc123
172
+
173
+
# Output to file (filename supports handlebars)
174
+
sitebase doc export abc123 -o "{{publishedAt}}_{{slug title}}.md"
175
+
176
+
# With content template
177
+
sitebase doc export abc123 -t ./templates/post.hbs -o ./content/my-post.md
178
+
```
179
+
180
+
**Options:**
181
+
182
+
| Option | Description |
183
+
|--------|-------------|
184
+
| `-o, --output <file>` | Output filename (supports handlebars: `{{title}}`, `{{slug title}}`, `{{publishedAt}}`, etc.) |
185
+
| `-t, --template <file>` | Handlebars template file for content |
186
+
| `--stdout` | Output to stdout (default if no `-o`) |
187
+
188
+
### Drafts
189
+
190
+
Drafts are stored in a separate `pub.sitebase.draft` collection, not as `site.standard.document` records. This keeps unpublished work separate from your public documents.
191
+
192
+
See [lexicons.md](./lexicons.md) for the draft schema.
193
+
194
+
#### `draft list`
195
+
196
+
Lists all drafts for the target publication.
197
+
198
+
```bash
199
+
sitebase draft list
200
+
```
201
+
202
+
#### `draft new`
203
+
204
+
Creates a new draft and opens it in `$EDITOR`.
205
+
206
+
```bash
207
+
sitebase draft new
208
+
```
209
+
210
+
#### `draft edit <rkey>`
211
+
212
+
Opens a draft in `$EDITOR` for editing.
213
+
214
+
```bash
215
+
sitebase draft edit abc123
216
+
```
217
+
218
+
#### `draft publish <rkey>`
219
+
220
+
Publishes a draft as a `site.standard.document`.
221
+
222
+
- Creates a new document record with `publishedAt` set to current time
223
+
- Deletes the draft record
224
+
225
+
```bash
226
+
sitebase draft publish abc123
227
+
```
228
+
229
+
#### `draft delete <rkey>`
230
+
231
+
Deletes a draft without publishing.
232
+
233
+
```bash
234
+
sitebase draft delete abc123
235
+
```