Highly ambitious ATProtocol AppView service and sdks
update cli readme
+114
-51
+114
-51
packages/cli/README.md
+114
-51
packages/cli/README.md
···
1
1
# @slices/cli
2
2
3
-
A command-line interface for managing AT Protocol lexicons and authentication with Slices.
3
+
A command-line interface for managing slice instances and AT Protocol lexicons
4
+
on https://slices.network.
4
5
5
6
## Features
6
7
7
-
- 🔐 **Device Code Authentication** - Secure OAuth 2.0 device flow login
8
-
- 📝 **Lexicon Management** - Import, list, and validate lexicon files
9
-
- 🧬 **Code Generation** - Generate TypeScript clients from lexicons
10
-
- ⚙️ **Project Configuration** - Optional `slices.json` config file support
11
-
- ✅ **Validation** - Built-in lexicon validation using `@slices/lexicon`
12
-
- 🔧 **Configuration Management** - Persistent authentication and settings
13
-
- 📊 **Progress Tracking** - Real-time progress for batch operations
8
+
- **Lexicon Management** - Push, pull, and list lexicon files in your slices
9
+
- **Code Generation** - Generate TypeScript clients from lexicons
10
+
- **Project Scaffolding** - Initialize new Deno SSR projects with OAuth
11
+
- **Project Configuration** - Optional `slices.json` config file support
14
12
15
13
## Installation
16
14
17
15
```bash
18
-
# Install from JSR
19
-
deno install -g -A jsr:@slices/cli
16
+
# Install globally from JSR
17
+
deno install -g -A jsr:@slices/cli --name slices
20
18
21
19
# Or run directly
22
20
deno run -A jsr:@slices/cli [command]
···
29
27
slices login
30
28
```
31
29
32
-
2. **Create a project config (optional)**
30
+
2. **Initialize a new project**
33
31
```bash
34
-
echo '{"slice": "at://did:plc:example/slice"}' > slices.json
32
+
slices init my-project
35
33
```
36
34
37
-
3. **Import lexicon files**
35
+
3. **Push lexicon files to your slice**
38
36
```bash
39
-
slices lexicon import
37
+
slices lexicon push
40
38
```
41
39
42
40
## Commands
43
41
44
42
### `slices login`
45
43
46
-
Authenticate with Slices using OAuth 2.0 device code flow.
44
+
Authenticate with Slices.
47
45
48
46
```bash
49
47
slices login [OPTIONS]
···
57
55
```
58
56
59
57
**Example:**
58
+
60
59
```bash
61
60
# Basic login
62
61
slices login
···
68
67
slices login --aip-url https://custom-aip.example.com
69
68
```
70
69
71
-
### `slices lexicon import`
70
+
### `slices lexicon push`
72
71
73
-
Import lexicon files to your slice with automatic validation.
72
+
Push lexicon files to your slice with automatic validation.
74
73
75
74
```bash
76
-
slices lexicon import [OPTIONS]
75
+
slices lexicon push [OPTIONS]
77
76
78
77
OPTIONS:
79
78
--path <PATH> Directory containing lexicon files (default: ./lexicons or from slices.json)
80
79
--slice <SLICE_URI> Target slice URI (required, or from slices.json)
80
+
--exclude-from-sync Exclude these lexicons from sync (sets excludedFromSync: true)
81
81
--validate-only Only validate files, don't upload
82
-
--dry-run Show what would be imported without uploading
82
+
--dry-run Show what would be pushed without uploading
83
+
--api-url <URL> Slices API base URL (default: https://api.slices.network or from slices.json)
84
+
-h, --help Show help
85
+
```
86
+
87
+
### `slices lexicon pull`
88
+
89
+
Pull lexicon files from your slice.
90
+
91
+
```bash
92
+
slices lexicon pull [OPTIONS]
93
+
94
+
OPTIONS:
95
+
--path <PATH> Directory to save lexicon files (default: ./lexicons or from slices.json)
96
+
--slice <SLICE_URI> Source slice URI (required, or from slices.json)
97
+
--nsid <PATTERN> Filter lexicons by NSID pattern (supports wildcards with *)
83
98
--api-url <URL> Slices API base URL (default: https://api.slices.network or from slices.json)
84
99
-h, --help Show help
85
100
```
···
97
112
-h, --help Show help
98
113
```
99
114
115
+
### `slices init`
116
+
117
+
Initialize a new Deno SSR project with OAuth authentication.
118
+
119
+
```bash
120
+
slices init <project-name>
121
+
slices init --name <project-name>
122
+
123
+
OPTIONS:
124
+
-n, --name <name> Project name
125
+
-h, --help Show help
126
+
```
127
+
128
+
### `slices status`
129
+
130
+
Show authentication and configuration status.
131
+
132
+
```bash
133
+
slices status [OPTIONS]
134
+
135
+
OPTIONS:
136
+
-h, --help Show help
137
+
```
138
+
139
+
### `slices logs`
140
+
141
+
View Jetstream logs for a slice.
142
+
143
+
```bash
144
+
slices logs [OPTIONS]
145
+
146
+
OPTIONS:
147
+
--slice <SLICE_URI> Target slice URI (optional, or from slices.json)
148
+
--limit <NUMBER> Maximum number of log entries to return (default: 100, max: 1000)
149
+
--api-url <URL> Slices API base URL (default: https://api.slices.network or from slices.json)
150
+
-h, --help Show help
151
+
```
152
+
100
153
### `slices codegen`
101
154
102
155
Generate TypeScript client from lexicon files.
···
113
166
```
114
167
115
168
**Examples:**
169
+
116
170
```bash
117
-
# Import all lexicons from ./lexicons (using slices.json config)
118
-
slices lexicon import
171
+
# Push all lexicons from ./lexicons (using slices.json config)
172
+
slices lexicon push
119
173
120
-
# Import from custom directory
121
-
slices lexicon import --path ./my-lexicons --slice at://did:plc:example/slice
174
+
# Push from custom directory
175
+
slices lexicon push --path ./my-lexicons --slice at://did:plc:example/slice
122
176
123
177
# Validate only (no upload)
124
-
slices lexicon import --validate-only --path ./lexicons
178
+
slices lexicon push --validate-only --path ./lexicons
179
+
180
+
# Dry run (see what would be pushed)
181
+
slices lexicon push --dry-run
125
182
126
-
# Dry run (see what would be imported)
127
-
slices lexicon import --dry-run
183
+
# Pull lexicons from slice
184
+
slices lexicon pull
128
185
129
186
# List lexicons in slice
130
187
slices lexicon list
131
188
132
189
# Generate TypeScript client
133
190
slices codegen
191
+
192
+
# Initialize new project
193
+
slices init my-project
194
+
195
+
# View slice logs
196
+
slices logs --slice at://did:plc:example/slice
134
197
```
135
198
136
199
## Global Options
···
141
204
142
205
## Configuration
143
206
144
-
### Authentication Config
207
+
### CLI Configuration
145
208
146
-
The CLI stores authentication and configuration in `~/.config/slices/config.json`.
209
+
The CLI stores configuration in `~/.config/slices/config.json`.
147
210
148
-
**Authentication config structure:**
211
+
**Config structure:**
212
+
149
213
```json
150
214
{
151
215
"auth": {
···
160
224
161
225
### Project Config
162
226
163
-
Create a `slices.json` file in your project root to avoid passing common options every time:
227
+
Create a `slices.json` file in your project root to avoid passing common options
228
+
every time:
164
229
165
230
```json
166
231
{
···
172
237
```
173
238
174
239
**Config options:**
175
-
- `slice` - Your slice URI (used by `lexicon import`, `lexicon list`, `codegen`)
240
+
241
+
- `slice` - Your slice URI (used by `lexicon push`, `lexicon pull`,
242
+
`lexicon list`, `codegen`)
176
243
- `lexiconPath` - Directory containing lexicon files (default: `./lexicons`)
177
-
- `clientOutputPath` - Output path for generated TypeScript client (default: `./generated_client.ts`)
244
+
- `clientOutputPath` - Output path for generated TypeScript client (default:
245
+
`./generated_client.ts`)
178
246
- `apiUrl` - Slices API base URL (default: `https://api.slices.network`)
179
247
180
-
The CLI will search for `slices.json` starting from the current directory and walking up the directory tree. Command line arguments always take precedence over config file values.
248
+
The CLI will search for `slices.json` starting from the current directory and
249
+
walking up the directory tree. Command line arguments always take precedence
250
+
over config file values.
181
251
182
252
## Lexicon File Requirements
183
253
184
-
Lexicon files must be valid JSON files with the following structure:
254
+
Lexicon files must be valid JSON files with the following structure. For the
255
+
full specification, see https://atproto.com/specs/lexicon.
185
256
186
257
```json
187
258
{
···
200
271
```
201
272
202
273
The CLI will:
274
+
203
275
1. Scan the specified directory for `.json` files
204
276
2. Validate each file using `@slices/lexicon`
205
277
3. Report validation errors with specific feedback
···
222
294
223
295
The CLI provides detailed error messages and suggestions:
224
296
225
-
- **Authentication errors** - Prompts to run `slices login`
297
+
- **Login errors** - Prompts to run `slices login`
226
298
- **Validation errors** - Shows specific issues with lexicon files
227
299
- **Network errors** - Displays connection and API errors
228
300
- **File errors** - Reports missing files or invalid JSON
···
235
307
# 1. Authenticate
236
308
slices login
237
309
238
-
# 2. Set up project config
239
-
echo '{"slice": "at://did:plc:user123/awesome-slice"}' > slices.json
310
+
# 2. Initialize project
311
+
slices init awesome-slice
240
312
241
313
# 3. Validate lexicons first
242
-
slices lexicon import --validate-only
314
+
slices lexicon push --validate-only
243
315
244
-
# 4. Import to slice
245
-
slices lexicon import
316
+
# 4. Push to slice
317
+
slices lexicon push
246
318
247
319
# 5. Generate TypeScript client
248
320
slices codegen
249
321
250
-
# 6. List imported lexicons
322
+
# 6. List lexicons
251
323
slices lexicon list
252
324
```
253
325
254
-
### Working Without Config File
255
-
256
-
```bash
257
-
# Import multiple lexicon directories
258
-
for dir in ./lexicons/*/; do
259
-
slices lexicon import --slice at://did:plc:user123/slice --path "$dir"
260
-
done
261
-
```
262
-
263
326
## License
264
327
265
-
MIT
328
+
MIT