-354

website/content/docs/cli.md

reviewed

··· 1 1 - +++ 2 2 - title = "CLI Reference" 3 3 - description = "Command-line tool documentation" 4 4 - weight = 3 5 5 - +++ 6 6 - 7 7 - ## Installation 8 8 - 9 9 - Clone and build from source: 10 10 - 11 11 - ```bash 12 12 - git clone https://tangled.org/@stavola.xyz/mlf 13 13 - cd mlf 14 14 - cargo build --release 15 15 - ``` 16 16 - 17 17 - The binary will be at `target/release/mlf`. 18 18 - 19 19 - ### Install with cargo 20 20 - 21 21 - ```bash 22 22 - # Install with all code generators (default: TypeScript, Go, Rust + JSON) 23 23 - cargo install --path mlf-cli --all-features 24 24 - 25 25 - # Install with only specific generators 26 26 - cargo install --path mlf-cli --no-default-features --features typescript 27 27 - cargo install --path mlf-cli --no-default-features --features typescript,go 28 28 - 29 29 - # Install with JSON generation only (minimal) 30 30 - cargo install --path mlf-cli --no-default-features 31 31 - ``` 32 32 - 33 33 - ### Available Features 34 34 - 35 35 - The CLI uses cargo features for optional code generators: 36 36 - 37 37 - - `typescript` - TypeScript type definitions and interfaces 38 38 - - `go` - Go structs with JSON tags 39 39 - - `rust` - Rust structs with serde derive macros 40 40 - - **default** = `["typescript", "go", "rust"]` - All generators enabled 41 41 - 42 42 - The JSON lexicon generator is always available (built into `mlf-codegen`). 43 43 - 44 44 - ## Commands 45 45 - 46 46 - ### `mlf check` 47 47 - 48 48 - Validate MLF lexicon files for syntax and type errors. 49 49 - 50 50 - ```bash 51 51 - mlf check [INPUT]... 52 52 - ``` 53 53 - 54 54 - **Arguments:** 55 55 - - `[INPUT]...` - MLF lexicon file(s) to validate (glob patterns supported) 56 56 - 57 57 - **Examples:** 58 58 - 59 59 - ```bash 60 60 - # Check a single file 61 61 - mlf check thread.mlf 62 62 - 63 63 - # Check multiple files 64 64 - mlf check thread.mlf profile.mlf reply.mlf 65 65 - 66 66 - # Check with glob patterns 67 67 - mlf check "lexicons/**/*.mlf" 68 68 - ``` 69 69 - 70 70 - **Output:** 71 71 - - ✓ Success message if valid 72 72 - - Detailed error messages with source context if invalid 73 73 - 74 74 - --- 75 75 - 76 76 - ### `mlf validate` 77 77 - 78 78 - Validate a JSON record against an MLF lexicon. 79 79 - 80 80 - ```bash 81 81 - mlf validate <LEXICON> <RECORD> 82 82 - ``` 83 83 - 84 84 - **Arguments:** 85 85 - - `<LEXICON>` - MLF lexicon file 86 86 - - `<RECORD>` - JSON record file to validate against the lexicon 87 87 - 88 88 - **Example:** 89 89 - 90 90 - ```bash 91 91 - mlf validate thread.mlf record.json 92 92 - ``` 93 93 - 94 94 - **Output:** 95 95 - - ✓ Success if record is valid 96 96 - - Detailed validation errors if invalid 97 97 - 98 98 - --- 99 99 - 100 100 - ### `mlf generate lexicon` 101 101 - 102 102 - Generate ATProto JSON lexicons from MLF files. 103 103 - 104 104 - ```bash 105 105 - mlf generate lexicon --output <OUTPUT> [OPTIONS] 106 106 - ``` 107 107 - 108 108 - **Options:** 109 109 - - `-i, --input <INPUT>` - Input MLF files (glob patterns supported, can be specified multiple times) 110 110 - - `-o, --output <OUTPUT>` - Output directory (required) 111 111 - - `--flat` - Use flat file structure (e.g., `com.example.thread.json`) 112 112 - 113 113 - **Examples:** 114 114 - 115 115 - ```bash 116 116 - # Generate with folder structure 117 117 - mlf generate lexicon -i thread.mlf -o lexicons/ 118 118 - # Creates: lexicons/com/example/thread.json 119 119 - 120 120 - # Generate with flat structure 121 121 - mlf generate lexicon -i thread.mlf -o lexicons/ --flat 122 122 - # Creates: lexicons/com.example.thread.json 123 123 - 124 124 - # Generate from multiple files 125 125 - mlf generate lexicon -i thread.mlf -i reply.mlf -o lexicons/ 126 126 - 127 127 - # Generate from glob pattern 128 128 - mlf generate lexicon -i "src/**/*.mlf" -o dist/lexicons/ 129 129 - ``` 130 130 - 131 131 - --- 132 132 - 133 133 - ### `mlf generate code` 134 134 - 135 135 - Generate code in various programming languages from MLF files. 136 136 - 137 137 - ```bash 138 138 - mlf generate code --generator <GENERATOR> --output <OUTPUT> [OPTIONS] 139 139 - ``` 140 140 - 141 141 - **Options:** 142 142 - - `-g, --generator <GENERATOR>` - Generator to use: `json`, `typescript`, `go`, or `rust` (required) 143 143 - - `-i, --input <INPUT>` - Input MLF files (glob patterns supported, can be specified multiple times) 144 144 - - `-o, --output <OUTPUT>` - Output directory (required) 145 145 - - `--flat` - Use flat file structure (e.g., `com.example.thread.ts`) 146 146 - 147 147 - **Available Generators:** 148 148 - 149 149 - | Generator | Output | Description | 150 150 - |-----------|--------|-------------| 151 151 - | `json` | `.json` | AT Protocol JSON lexicons (always available) | 152 152 - | `typescript` | `.ts` | TypeScript interfaces with JSDoc comments | 153 153 - | `go` | `.go` | Go structs with JSON tags and proper capitalization | 154 154 - | `rust` | `.rs` | Rust structs with serde derive macros | 155 155 - 156 156 - **TypeScript Example:** 157 157 - 158 158 - ```bash 159 159 - mlf generate code -g typescript -i thread.mlf -o src/types/ 160 160 - # Creates: src/types/com/example/thread.ts 161 161 - ``` 162 162 - 163 163 - Generated TypeScript: 164 164 - ```typescript 165 165 - /** 166 166 - * Generated from com.example.thread 167 167 - * Do not edit manually 168 168 - */ 169 169 - 170 170 - export interface Thread { 171 171 - /** Thread title */ 172 172 - title: string; 173 173 - /** Creation timestamp */ 174 174 - createdAt: string; 175 175 - posts: Post[]; 176 176 - } 177 177 - ``` 178 178 - 179 179 - **Go Example:** 180 180 - 181 181 - ```bash 182 182 - mlf generate code -g go -i thread.mlf -o pkg/models/ 183 183 - # Creates: pkg/models/com/example/thread.go 184 184 - ``` 185 185 - 186 186 - Generated Go: 187 187 - ```go 188 188 - // Generated from com.example.thread 189 189 - // Do not edit manually 190 190 - 191 191 - package thread 192 192 - 193 193 - // Thread represents a discussion thread 194 194 - type Thread struct { 195 195 - // Thread title 196 196 - Title string `json:"title"` 197 197 - // Creation timestamp 198 198 - CreatedAt string `json:"createdAt"` 199 199 - Posts []Post `json:"posts"` 200 200 - } 201 201 - ``` 202 202 - 203 203 - **Rust Example:** 204 204 - 205 205 - ```bash 206 206 - mlf generate code -g rust -i thread.mlf -o src/models/ 207 207 - # Creates: src/models/com/example/thread.rs 208 208 - ``` 209 209 - 210 210 - Generated Rust: 211 211 - ```rust 212 212 - // Generated from com.example.thread 213 213 - // Do not edit manually 214 214 - 215 215 - use serde::{Deserialize, Serialize}; 216 216 - 217 217 - /// Thread represents a discussion thread 218 218 - #[derive(Debug, Clone, Serialize, Deserialize)] 219 219 - pub struct Thread { 220 220 - /// Thread title 221 221 - pub title: String, 222 222 - /// Creation timestamp 223 223 - #[serde(rename = "createdAt")] 224 224 - pub created_at: String, 225 225 - pub posts: Vec<Post>, 226 226 - } 227 227 - ``` 228 228 - 229 229 - **Notes:** 230 230 - 231 231 - - TypeScript: Uses interfaces for records, type aliases for defs, optional fields use `?` 232 232 - - Go: Uses structs with JSON tags, pointer types for optional fields, PascalCase for exports 233 233 - - Rust: Uses structs with serde, `Option<T>` for optional fields, snake_case with `#[serde(rename)]` 234 234 - - All generators handle doc comments, constraints are preserved in generated code where applicable 235 235 - 236 236 - --- 237 237 - 238 238 - ### `mlf generate mlf` 239 239 - 240 240 - Convert ATProto JSON lexicons back to MLF format. 241 241 - 242 242 - ```bash 243 243 - mlf generate mlf --output <OUTPUT> [OPTIONS] 244 244 - ``` 245 245 - 246 246 - **Options:** 247 247 - - `-i, --input <INPUT>` - Input JSON lexicon files (glob patterns supported, can be specified multiple times) 248 248 - - `-o, --output <OUTPUT>` - Output directory (required) 249 249 - 250 250 - **Examples:** 251 251 - 252 252 - ```bash 253 253 - # Convert a single JSON lexicon to MLF 254 254 - mlf generate mlf -i com.example.thread.json -o ./lexicons/ 255 255 - # Creates: lexicons/com/example/thread.mlf 256 256 - 257 257 - # Convert multiple JSON lexicons 258 258 - mlf generate mlf -i lexicon1.json -i lexicon2.json -o ./mlf/ 259 259 - 260 260 - # Convert using glob pattern 261 261 - mlf generate mlf -i "dist/lexicons/**/*.json" -o ./src/ 262 262 - ``` 263 263 - 264 264 - **Features:** 265 265 - 266 266 - - **Smart type conversion** - Automatically converts format strings (did, datetime, handle) to prelude types (Did, Datetime, Handle) 267 267 - - **Proper formatting** - Generates clean, properly indented MLF with correct syntax 268 268 - - **Reference conversion** - Converts `namespace#name` refs to `namespace.name` notation 269 269 - - **Complete coverage** - Supports records, queries, procedures, subscriptions, tokens, and type definitions 270 270 - 271 271 - **Input format:** 272 272 - 273 273 - The JSON lexicon must be a valid ATProto lexicon with: 274 274 - - `lexicon: 1` version field 275 275 - - `id` field containing the namespace 276 276 - - `defs` object with type definitions 277 277 - 278 278 - **Example:** 279 279 - 280 280 - Given a JSON lexicon: 281 281 - ```json 282 282 - { 283 283 - "lexicon": 1, 284 284 - "id": "com.example.thread", 285 285 - "defs": { 286 286 - "main": { 287 287 - "type": "record", 288 288 - "key": "tid", 289 289 - "record": { 290 290 - "type": "object", 291 291 - "required": ["title", "createdAt"], 292 292 - "properties": { 293 293 - "title": { 294 294 - "type": "string", 295 295 - "maxLength": 200 296 296 - }, 297 297 - "createdAt": { 298 298 - "type": "string", 299 299 - "format": "datetime" 300 300 - } 301 301 - } 302 302 - } 303 303 - } 304 304 - } 305 305 - } 306 306 - ``` 307 307 - 308 308 - Generates MLF: 309 309 - ```mlf 310 310 - record main { 311 311 - title!: string constrained { 312 312 - maxLength: 200, 313 313 - }, 314 314 - createdAt!: Datetime, 315 315 - }; 316 316 - ``` 317 317 - 318 318 - **Use cases:** 319 319 - 320 320 - - **Migration** - Convert existing JSON lexicons to MLF format 321 321 - - **Interoperability** - Work with lexicons from other tools or repositories 322 322 - - **Comparison** - Generate MLF from JSON to compare with hand-written MLF 323 323 - - **Learning** - See how JSON lexicons translate to MLF syntax 324 324 - 325 325 - --- 326 326 - 327 327 - ## Error Messages 328 328 - 329 329 - MLF provides rich error messages with: 330 330 - 331 331 - - Source code context 332 332 - - Labeled spans showing exact error locations 333 333 - - Helpful suggestions for fixing errors 334 334 - - Error codes for categorization 335 335 - 336 336 - **Example error:** 337 337 - 338 338 - ``` 339 339 - × Undefined reference to 'ProfileView' 340 340 - ╭─[profile.mlf:5:12] 341 341 - 5 │ author: ProfileView, 342 342 - · ^^^^^^^^^^^ 'ProfileView' is not defined 343 343 - ╰──── 344 344 - help: Make sure this type is defined in the same file or imported via 'use'. 345 345 - ``` 346 346 - 347 347 - ## Environment Variables 348 348 - 349 349 - None currently used. 350 350 - 351 351 - ## Exit Codes 352 352 - 353 353 - - `0` - Success 354 354 - - `1` - Error (syntax, validation, or runtime error)

+77

website/content/docs/cli/01-installation.md

reviewed

··· 1 1 + +++ 2 2 + title = "Installation" 3 3 + description = "How to install the MLF CLI" 4 4 + weight = 1 5 5 + +++ 6 6 + 7 7 + ## Building from Source 8 8 + 9 9 + Clone and build from source: 10 10 + 11 11 + ```bash 12 12 + git clone https://tangled.org/@stavola.xyz/mlf 13 13 + cd mlf 14 14 + cargo build --release 15 15 + ``` 16 16 + 17 17 + The binary will be at `target/release/mlf`. 18 18 + 19 19 + ## Installing with Cargo 20 20 + 21 21 + ### All Features (Recommended) 22 22 + 23 23 + Install with all code generators enabled: 24 24 + 25 25 + ```bash 26 26 + cargo install --path mlf-cli --all-features 27 27 + ``` 28 28 + 29 29 + This includes TypeScript, Go, Rust, and JSON lexicon generators. 30 30 + 31 31 + ### Selective Installation 32 32 + 33 33 + Install only specific generators to reduce compilation time and binary size: 34 34 + 35 35 + ```bash 36 36 + # TypeScript only 37 37 + cargo install --path mlf-cli --no-default-features --features typescript 38 38 + 39 39 + # TypeScript and Go 40 40 + cargo install --path mlf-cli --no-default-features --features typescript,go 41 41 + 42 42 + # Minimal (JSON lexicon generation only) 43 43 + cargo install --path mlf-cli --no-default-features 44 44 + ``` 45 45 + 46 46 + ## Available Features 47 47 + 48 48 + The CLI uses cargo features for optional code generators: 49 49 + 50 50 + | Feature | Description | Output Format | 51 51 + |---------|-------------|---------------| 52 52 + | `typescript` | TypeScript type definitions and interfaces | `.ts` | 53 53 + | `go` | Go structs with JSON tags | `.go` | 54 54 + | `rust` | Rust structs with serde derive macros | `.rs` | 55 55 + | (built-in) | JSON lexicon generator | `.json` | 56 56 + 57 57 + **Default features:** `["typescript", "go", "rust"]` - All generators enabled. 58 58 + 59 59 + The JSON lexicon generator is always available (built into `mlf-codegen` core). 60 60 + 61 61 + ## Verify Installation 62 62 + 63 63 + After installation, verify the CLI is working: 64 64 + 65 65 + ```bash 66 66 + mlf --version 67 67 + mlf --help 68 68 + ``` 69 69 + 70 70 + ## Next Steps 71 71 + 72 72 + Once installed, you can: 73 73 + 74 74 + 1. [Configure your project](02-configuration.md) with an `mlf.toml` file 75 75 + 2. [Check MLF files](03-check.md) for syntax and type errors 76 76 + 3. [Generate code](05-generate.md) in your preferred language 77 77 + 4. [Fetch remote lexicons](06-fetch.md) from ATProto repositories

+216

website/content/docs/cli/02-configuration.md

reviewed

··· 1 1 + +++ 2 2 + title = "Configuration" 3 3 + description = "Project configuration with mlf.toml" 4 4 + weight = 2 5 5 + +++ 6 6 + 7 7 + MLF projects can be configured with an `mlf.toml` file that specifies source directories, output configurations, and dependencies. This allows you to run commands without repeatedly specifying arguments. 8 8 + 9 9 + ## Basic Structure 10 10 + 11 11 + Create an `mlf.toml` file in your project root: 12 12 + 13 13 + ```toml 14 14 + [source] 15 15 + directory = "./lexicons" 16 16 + 17 17 + [[output]] 18 18 + type = "lexicon" 19 19 + directory = "./dist/lexicons" 20 20 + 21 21 + [[output]] 22 22 + type = "typescript" 23 23 + directory = "./src/types" 24 24 + 25 25 + [dependencies] 26 26 + dependencies = ["stream.place", "app.bsky"] 27 27 + ``` 28 28 + 29 29 + ## Configuration Sections 30 30 + 31 31 + ### Source Directory 32 32 + 33 33 + The `[source]` section specifies where your MLF files are located: 34 34 + 35 35 + ```toml 36 36 + [source] 37 37 + directory = "./lexicons" 38 38 + ``` 39 39 + 40 40 + **Default:** `"./lexicons"` 41 41 + 42 42 + This directory is used by: 43 43 + - `mlf check` (when run without arguments) 44 44 + - `mlf generate` (when run without arguments) 45 45 + 46 46 + ### Output Configurations 47 47 + 48 48 + The `[[output]]` section defines code generation targets. You can have multiple output blocks: 49 49 + 50 50 + ```toml 51 51 + [[output]] 52 52 + type = "lexicon" 53 53 + directory = "./dist/lexicons" 54 54 + 55 55 + [[output]] 56 56 + type = "typescript" 57 57 + directory = "./src/types" 58 58 + 59 59 + [[output]] 60 60 + type = "go" 61 61 + directory = "./pkg/lexicons" 62 62 + 63 63 + [[output]] 64 64 + type = "rust" 65 65 + directory = "./src/lexicons" 66 66 + ``` 67 67 + 68 68 + **Supported types:** 69 69 + - `"lexicon"` - Generate JSON lexicons 70 70 + - `"typescript"` - Generate TypeScript types 71 71 + - `"go"` - Generate Go structs 72 72 + - `"rust"` - Generate Rust structs 73 73 + 74 74 + When you run `mlf generate` without arguments, it will generate all configured outputs. 75 75 + 76 76 + ### Dependencies 77 77 + 78 78 + The `[dependencies]` section lists external lexicon namespaces to fetch: 79 79 + 80 80 + ```toml 81 81 + [dependencies] 82 82 + dependencies = [ 83 83 + "stream.place", 84 84 + "app.bsky", 85 85 + "com.atproto" 86 86 + ] 87 87 + ``` 88 88 + 89 89 + These dependencies are fetched when you run `mlf fetch` without arguments. 90 90 + 91 91 + ## Commands Using Configuration 92 92 + 93 93 + ### `mlf check` 94 94 + 95 95 + When run without arguments, checks all files in the source directory: 96 96 + 97 97 + ```bash 98 98 + mlf check 99 99 + # Equivalent to: mlf check "./lexicons/**/*.mlf" 100 100 + ``` 101 101 + 102 102 + ### `mlf generate` 103 103 + 104 104 + When run without a subcommand, generates all configured outputs: 105 105 + 106 106 + ```bash 107 107 + mlf generate 108 108 + # Runs all [[output]] configurations 109 109 + ``` 110 110 + 111 111 + ### `mlf fetch` 112 112 + 113 113 + When run without arguments, fetches all dependencies: 114 114 + 115 115 + ```bash 116 116 + mlf fetch 117 117 + # Fetches: stream.place, app.bsky, com.atproto 118 118 + ``` 119 119 + 120 120 + Add `--save` flag to automatically update `mlf.toml`: 121 121 + 122 122 + ```bash 123 123 + mlf fetch stream.place --save 124 124 + # Downloads lexicons AND adds to dependencies array 125 125 + ``` 126 126 + 127 127 + ## Complete Example 128 128 + 129 129 + Here's a complete `mlf.toml` for a TypeScript project using ATProto lexicons: 130 130 + 131 131 + ```toml 132 132 + [source] 133 133 + directory = "./lexicons" 134 134 + 135 135 + [[output]] 136 136 + type = "lexicon" 137 137 + directory = "./dist/lexicons" 138 138 + 139 139 + [[output]] 140 140 + type = "typescript" 141 141 + directory = "./src/types" 142 142 + 143 143 + [dependencies] 144 144 + dependencies = [ 145 145 + "app.bsky", 146 146 + "com.atproto", 147 147 + "chat.bsky" 148 148 + ] 149 149 + ``` 150 150 + 151 151 + ### Workflow 152 152 + 153 153 + 1. **Fetch dependencies:** 154 154 + ```bash 155 155 + mlf fetch 156 156 + ``` 157 157 + Downloads `app.bsky`, `com.atproto`, and `chat.bsky` lexicons to `.mlf/lexicons/` 158 158 + 159 159 + 2. **Write your lexicons:** 160 160 + Create `.mlf` files in `./lexicons/` that reference the fetched lexicons 161 161 + 162 162 + 3. **Check for errors:** 163 163 + ```bash 164 164 + mlf check 165 165 + ``` 166 166 + Validates all MLF files in `./lexicons/` 167 167 + 168 168 + 4. **Generate outputs:** 169 169 + ```bash 170 170 + mlf generate 171 171 + ``` 172 172 + Creates: 173 173 + - JSON lexicons in `./dist/lexicons/` 174 174 + - TypeScript types in `./src/types/` 175 175 + 176 176 + ## Fetched Lexicons Cache 177 177 + 178 178 + When you fetch lexicons, they're stored in `.mlf/lexicons/`: 179 179 + 180 180 + ``` 181 181 + .mlf/ 182 182 + ├── .gitignore # Automatically created 183 183 + ├── .lexicon-cache.toml # Metadata about fetched lexicons 184 184 + └── lexicons/ 185 185 + ├── json/ # Original JSON lexicons 186 186 + │ ├── app.bsky.actor.profile.json 187 187 + │ └── ... 188 188 + └── mlf/ # Converted MLF format 189 189 + ├── app.bsky.actor.profile.mlf 190 190 + └── ... 191 191 + ``` 192 192 + 193 193 + The `.mlf` directory is automatically added to `.gitignore`, so fetched lexicons won't be committed to your repository. 194 194 + 195 195 + ## Best Practices 196 196 + 197 197 + 1. **Commit `mlf.toml`** - Version control your configuration 198 198 + 2. **Don't commit `.mlf/`** - Let each developer fetch dependencies 199 199 + 3. **Use semantic namespaces** - Organize lexicons by domain 200 200 + 4. **Multiple outputs** - Generate both lexicons and code simultaneously 201 201 + 5. **CI/CD integration** - Run `mlf check` in your CI pipeline 202 202 + 203 203 + ## Override Configuration 204 204 + 205 205 + You can always override configuration with explicit arguments: 206 206 + 207 207 + ```bash 208 208 + # Override source directory 209 209 + mlf check "./other-lexicons/**/*.mlf" 210 210 + 211 211 + # Override output 212 212 + mlf generate lexicon -i custom.mlf -o ./custom-output/ 213 213 + 214 214 + # Fetch specific namespace (ignoring dependencies list) 215 215 + mlf fetch stream.place 216 216 + ```

+191

website/content/docs/cli/03-check.md

reviewed

··· 1 1 + +++ 2 2 + title = "Check Command" 3 3 + description = "Validate MLF lexicon files" 4 4 + weight = 3 5 5 + +++ 6 6 + 7 7 + The `mlf check` command validates MLF lexicon files for syntax and type errors. 8 8 + 9 9 + ## Usage 10 10 + 11 11 + ```bash 12 12 + mlf check [INPUT]... 13 13 + ``` 14 14 + 15 15 + **Arguments:** 16 16 + - `[INPUT]...` - MLF lexicon file(s) to validate (glob patterns supported) 17 17 + 18 18 + If no input files are provided, `mlf check` will use the source directory from your `mlf.toml` configuration. 19 19 + 20 20 + ## Examples 21 21 + 22 22 + ### Check with Configuration 23 23 + 24 24 + If you have an `mlf.toml` file: 25 25 + 26 26 + ```toml 27 27 + [source] 28 28 + directory = "./lexicons" 29 29 + ``` 30 30 + 31 31 + Simply run: 32 32 + 33 33 + ```bash 34 34 + mlf check 35 35 + ``` 36 36 + 37 37 + This automatically checks all `.mlf` files in `./lexicons/`. 38 38 + 39 39 + ### Check Specific Files 40 40 + 41 41 + ```bash 42 42 + # Check a single file 43 43 + mlf check thread.mlf 44 44 + 45 45 + # Check multiple files 46 46 + mlf check thread.mlf profile.mlf reply.mlf 47 47 + ``` 48 48 + 49 49 + ### Check with Glob Patterns 50 50 + 51 51 + ```bash 52 52 + # Check all MLF files in a directory 53 53 + mlf check "lexicons/**/*.mlf" 54 54 + 55 55 + # Check files matching a pattern 56 56 + mlf check "src/*/schema.mlf" 57 57 + 58 58 + # Check all MLF files recursively 59 59 + mlf check "**/*.mlf" 60 60 + ``` 61 61 + 62 62 + ## Validation Checks 63 63 + 64 64 + The check command performs comprehensive validation: 65 65 + 66 66 + ### 1. **Syntax Validation** 67 67 + - Correct MLF syntax 68 68 + - Proper use of keywords 69 69 + - Valid identifiers and namespaces 70 70 + - Correct constraint syntax 71 71 + 72 72 + ### 2. **Type Validation** 73 73 + - All referenced types exist 74 74 + - Type constraints are valid 75 75 + - Required fields are properly marked 76 76 + - Array and object structures are correct 77 77 + 78 78 + ### 3. **Semantic Validation** 79 79 + - No duplicate definitions 80 80 + - Valid record keys 81 81 + - Proper XRPC method signatures 82 82 + - Correct union type usage 83 83 + 84 84 + ### 4. **Cross-Reference Validation** 85 85 + - External references resolve correctly 86 86 + - Import statements are valid 87 87 + - Prelude types are accessible 88 88 + - Fetched dependencies are available 89 89 + 90 90 + ## Output 91 91 + 92 92 + ### Success 93 93 + 94 94 + When all files are valid: 95 95 + 96 96 + ``` 97 97 + ✓ thread.mlf: Parsed successfully 98 98 + ✓ profile.mlf: Parsed successfully 99 99 + ✓ reply.mlf: Parsed successfully 100 100 + 101 101 + ✓ All lexicons are valid 102 102 + ``` 103 103 + 104 104 + ### Errors 105 105 + 106 106 + When errors are found, detailed diagnostics are shown: 107 107 + 108 108 + ``` 109 109 + × Undefined reference to 'ProfileView' 110 110 + ╭─[profile.mlf:5:12] 111 111 + 5 │ author: ProfileView, 112 112 + · ^^^^^^^^^^^ 'ProfileView' is not defined 113 113 + ╰──── 114 114 + help: Make sure this type is defined in the same file or imported via 'use'. 115 115 + ``` 116 116 + 117 117 + Each error includes: 118 118 + - Error message with context 119 119 + - Source code snippet 120 120 + - Exact location (line and column) 121 121 + - Helpful suggestions for fixing 122 122 + 123 123 + ## Working with Dependencies 124 124 + 125 125 + If your lexicons reference external types (e.g., from `app.bsky` or `com.atproto`), make sure to fetch them first: 126 126 + 127 127 + ```bash 128 128 + # Fetch dependencies 129 129 + mlf fetch 130 130 + 131 131 + # Then check your lexicons 132 132 + mlf check 133 133 + ``` 134 134 + 135 135 + The check command automatically loads lexicons from `.mlf/lexicons/mlf/` if they exist. 136 136 + 137 137 + ## Exit Codes 138 138 + 139 139 + - `0` - All files are valid 140 140 + - `1` - Validation errors found 141 141 + 142 142 + ## Common Issues 143 143 + 144 144 + ### Undefined Reference 145 145 + 146 146 + ``` 147 147 + × Undefined reference to 'SomeType' 148 148 + ``` 149 149 + 150 150 + **Solution:** 151 151 + - Define `SomeType` in the same file, or 152 152 + - Fetch the lexicon containing `SomeType` using `mlf fetch`, or 153 153 + - Add an import statement if needed 154 154 + 155 155 + ### Parse Error 156 156 + 157 157 + ``` 158 158 + × Expected 'constrained', found 'contsrained' 159 159 + ``` 160 160 + 161 161 + **Solution:** Fix the typo in your MLF file 162 162 + 163 163 + ### Type Mismatch 164 164 + 165 165 + ``` 166 166 + × Field 'count' expects integer, found string 167 167 + ``` 168 168 + 169 169 + **Solution:** Correct the field type to match the schema 170 170 + 171 171 + ## Integration with CI/CD 172 172 + 173 173 + Use `mlf check` in your continuous integration pipeline: 174 174 + 175 175 + ```yaml 176 176 + # GitHub Actions example 177 177 + - name: Validate MLF Lexicons 178 178 + run: | 179 179 + mlf fetch 180 180 + mlf check 181 181 + ``` 182 182 + 183 183 + This ensures all lexicons remain valid as your project evolves. 184 184 + 185 185 + ## Tips 186 186 + 187 187 + 1. **Use configuration** - Set up `mlf.toml` to avoid typing paths repeatedly 188 188 + 2. **Check often** - Run `mlf check` frequently during development 189 189 + 3. **Version control** - Commit valid lexicons only 190 190 + 4. **Fetch first** - Always fetch dependencies before checking 191 191 + 5. **Read errors carefully** - MLF provides detailed error messages with helpful suggestions

+211

website/content/docs/cli/04-validate.md

reviewed

··· 1 1 + +++ 2 2 + title = "Validate Command" 3 3 + description = "Validate JSON records against lexicons" 4 4 + weight = 4 5 5 + +++ 6 6 + 7 7 + The `mlf validate` command validates JSON record data against an MLF lexicon schema. 8 8 + 9 9 + ## Usage 10 10 + 11 11 + ```bash 12 12 + mlf validate <LEXICON> <RECORD> 13 13 + ``` 14 14 + 15 15 + **Arguments:** 16 16 + - `<LEXICON>` - MLF lexicon file defining the schema 17 17 + - `<RECORD>` - JSON file containing the record to validate 18 18 + 19 19 + ## Example 20 20 + 21 21 + Given a lexicon file `thread.mlf`: 22 22 + 23 23 + ```mlf 24 24 + record main { 25 25 + title!: string constrained { 26 26 + maxLength: 200, 27 27 + }, 28 28 + createdAt!: Datetime, 29 29 + posts: Post[], 30 30 + }; 31 31 + 32 32 + def Post = { 33 33 + text!: string, 34 34 + createdAt!: Datetime, 35 35 + }; 36 36 + ``` 37 37 + 38 38 + And a JSON record file `my-thread.json`: 39 39 + 40 40 + ```json 41 41 + { 42 42 + "title": "My Discussion Thread", 43 43 + "createdAt": "2024-01-15T10:30:00Z", 44 44 + "posts": [ 45 45 + { 46 46 + "text": "First post!", 47 47 + "createdAt": "2024-01-15T10:30:00Z" 48 48 + } 49 49 + ] 50 50 + } 51 51 + ``` 52 52 + 53 53 + Validate the record: 54 54 + 55 55 + ```bash 56 56 + mlf validate thread.mlf my-thread.json 57 57 + ``` 58 58 + 59 59 + ## Output 60 60 + 61 61 + ### Valid Record 62 62 + 63 63 + ``` 64 64 + ✓ Lexicon parsed successfully 65 65 + ✓ JSON record parsed successfully 66 66 + ✓ Record is valid according to the lexicon schema 67 67 + ``` 68 68 + 69 69 + ### Invalid Record 70 70 + 71 71 + If the record doesn't match the schema: 72 72 + 73 73 + ``` 74 74 + ✗ Record validation failed with 2 error(s): 75 75 + • Field 'title' is required but missing 76 76 + • Field 'createdAt': expected string in datetime format, found "not-a-date" 77 77 + ``` 78 78 + 79 79 + ## Validation Rules 80 80 + 81 81 + The validate command checks: 82 82 + 83 83 + ### 1. **Required Fields** 84 84 + - All fields marked with `!` must be present 85 85 + - Optional fields can be omitted 86 86 + 87 87 + ### 2. **Type Matching** 88 88 + - String fields must be strings 89 89 + - Integer fields must be numbers 90 90 + - Arrays must be arrays 91 91 + - Objects must have correct structure 92 92 + 93 93 + ### 3. **Constraints** 94 94 + - String length constraints (`maxLength`, `minLength`) 95 95 + - String grapheme constraints (`maxGraphemes`, `minGraphemes`) 96 96 + - Integer range constraints (`minimum`, `maximum`) 97 97 + - Array length constraints 98 98 + - Format validation (`datetime`, `uri`, `at-uri`, etc.) 99 99 + 100 100 + ### 4. **Nested Structures** 101 101 + - Object fields are recursively validated 102 102 + - Array items match their item schema 103 103 + - References to other defs are resolved 104 104 + 105 105 + ## Use Cases 106 106 + 107 107 + ### 1. **Test Data Validation** 108 108 + 109 109 + Validate test fixtures before using them: 110 110 + 111 111 + ```bash 112 112 + mlf validate profile.mlf test-data/profile-1.json 113 113 + ``` 114 114 + 115 115 + ### 2. **API Response Validation** 116 116 + 117 117 + Check that API responses match your schema: 118 118 + 119 119 + ```bash 120 120 + curl https://api.example.com/profile > response.json 121 121 + mlf validate profile.mlf response.json 122 122 + ``` 123 123 + 124 124 + ### 3. **Schema Migration** 125 125 + 126 126 + When updating schemas, validate existing records against the new schema: 127 127 + 128 128 + ```bash 129 129 + # Validate all records 130 130 + for file in records/*.json; do 131 131 + mlf validate schema.mlf "$file" || echo "Failed: $file" 132 132 + done 133 133 + ``` 134 134 + 135 135 + ### 4. **Development Workflow** 136 136 + 137 137 + Validate records during development: 138 138 + 139 139 + ```bash 140 140 + # Write some test data 141 141 + echo '{"title": "Test", "createdAt": "2024-01-15T10:30:00Z"}' > test.json 142 142 + 143 143 + # Validate it 144 144 + mlf validate thread.mlf test.json 145 145 + ``` 146 146 + 147 147 + ## Common Validation Errors 148 148 + 149 149 + ### Missing Required Field 150 150 + 151 151 + ``` 152 152 + ✗ Field 'title' is required but missing 153 153 + ``` 154 154 + 155 155 + **Solution:** Add the required field to your JSON 156 156 + 157 157 + ### Type Mismatch 158 158 + 159 159 + ``` 160 160 + ✗ Field 'count': expected integer, found "123" 161 161 + ``` 162 162 + 163 163 + **Solution:** Use a number instead of a string: `"count": 123` 164 164 + 165 165 + ### Constraint Violation 166 166 + 167 167 + ``` 168 168 + ✗ Field 'title': string length 250 exceeds maxLength 200 169 169 + ``` 170 170 + 171 171 + **Solution:** Shorten the string to meet the constraint 172 172 + 173 173 + ### Invalid Format 174 174 + 175 175 + ``` 176 176 + ✗ Field 'createdAt': expected datetime format, found "2024-01-15" 177 177 + ``` 178 178 + 179 179 + **Solution:** Use full ISO 8601 datetime format: `"2024-01-15T10:30:00Z"` 180 180 + 181 181 + ### Invalid Array Item 182 182 + 183 183 + ``` 184 184 + ✗ Array item at index 0: Field 'text' is required but missing 185 185 + ``` 186 186 + 187 187 + **Solution:** Ensure all array items match the schema 188 188 + 189 189 + ## Exit Codes 190 190 + 191 191 + - `0` - Record is valid 192 192 + - `1` - Validation failed or error occurred 193 193 + 194 194 + ## Limitations 195 195 + 196 196 + The validate command currently validates against the lexicon structure but does not: 197 197 + 198 198 + - Validate CID references 199 199 + - Validate blob content types 200 200 + - Check external references 201 201 + - Verify cryptographic signatures 202 202 + 203 203 + These checks would typically be performed by the PDS or other ATProto infrastructure. 204 204 + 205 205 + ## Tips 206 206 + 207 207 + 1. **Start simple** - Validate basic records first, then add complexity 208 208 + 2. **Use test data** - Create JSON fixtures for your schemas 209 209 + 3. **Automate validation** - Add validation to your test suite 210 210 + 4. **Check constraints** - Pay attention to string lengths and ranges 211 211 + 5. **Format matters** - Use proper datetime/URI formats as specified by ATProto

+355

website/content/docs/cli/05-generate.md

reviewed

··· 1 1 + +++ 2 2 + title = "Generate Commands" 3 3 + description = "Generate code and lexicons from MLF" 4 4 + weight = 5 5 5 + +++ 6 6 + 7 7 + The `mlf generate` command converts MLF files to various output formats including JSON lexicons and code in multiple programming languages. 8 8 + 9 9 + ## Overview 10 10 + 11 11 + ```bash 12 12 + # Generate all configured outputs 13 13 + mlf generate 14 14 + 15 15 + # Generate JSON lexicons 16 16 + mlf generate lexicon -i <INPUT> -o <OUTPUT> 17 17 + 18 18 + # Generate code in a specific language 19 19 + mlf generate code -g <GENERATOR> -i <INPUT> -o <OUTPUT> 20 20 + 21 21 + # Convert JSON lexicons to MLF 22 22 + mlf generate mlf -i <INPUT> -o <OUTPUT> 23 23 + ``` 24 24 + 25 25 + ## Generate All Outputs 26 26 + 27 27 + When run without a subcommand, `mlf generate` uses your `mlf.toml` configuration to generate all specified outputs: 28 28 + 29 29 + ```toml 30 30 + [[output]] 31 31 + type = "lexicon" 32 32 + directory = "./dist/lexicons" 33 33 + 34 34 + [[output]] 35 35 + type = "typescript" 36 36 + directory = "./src/types" 37 37 + ``` 38 38 + 39 39 + ```bash 40 40 + mlf generate 41 41 + ``` 42 42 + 43 43 + This will: 44 44 + 1. Read the source directory from configuration 45 45 + 2. Process all `.mlf` files 46 46 + 3. Generate each configured output type 47 47 + 48 48 + **Output:** 49 49 + ``` 50 50 + Running 2 output configuration(s)... 51 51 + 52 52 + Generating lexicon output to ./dist/lexicons... 53 53 + Generated: ./dist/lexicons/com/example/thread.json 54 54 + ✓ Generated lexicon output successfully 55 55 + 56 56 + Generating typescript output to ./src/types... 57 57 + Generated: ./src/types/com/example/thread.ts 58 58 + ✓ Generated typescript output successfully 59 59 + 60 60 + ✓ Successfully generated all 2 output(s) 61 61 + ``` 62 62 + 63 63 + --- 64 64 + 65 65 + ## Generate Lexicon (JSON) 66 66 + 67 67 + Generate ATProto JSON lexicons from MLF files. 68 68 + 69 69 + ```bash 70 70 + mlf generate lexicon -i <INPUT> -o <OUTPUT> [OPTIONS] 71 71 + ``` 72 72 + 73 73 + **Options:** 74 74 + - `-i, --input <INPUT>` - Input MLF files (glob patterns supported, can be specified multiple times) 75 75 + - `-o, --output <OUTPUT>` - Output directory (required) 76 76 + - `--flat` - Use flat file structure (e.g., `com.example.thread.json`) 77 77 + 78 78 + **Examples:** 79 79 + 80 80 + ```bash 81 81 + # Generate with folder structure 82 82 + mlf generate lexicon -i thread.mlf -o lexicons/ 83 83 + # Creates: lexicons/com/example/thread.json 84 84 + 85 85 + # Generate with flat structure 86 86 + mlf generate lexicon -i thread.mlf -o lexicons/ --flat 87 87 + # Creates: lexicons/com.example.thread.json 88 88 + 89 89 + # Generate from multiple files 90 90 + mlf generate lexicon -i thread.mlf -i reply.mlf -o lexicons/ 91 91 + 92 92 + # Generate from glob pattern 93 93 + mlf generate lexicon -i "src/**/*.mlf" -o dist/lexicons/ 94 94 + ``` 95 95 + 96 96 + --- 97 97 + 98 98 + ## Generate Code 99 99 + 100 100 + Generate code in various programming languages from MLF files. 101 101 + 102 102 + ```bash 103 103 + mlf generate code -g <GENERATOR> -i <INPUT> -o <OUTPUT> [OPTIONS] 104 104 + ``` 105 105 + 106 106 + **Options:** 107 107 + - `-g, --generator <GENERATOR>` - Generator to use (required): `json`, `typescript`, `go`, or `rust` 108 108 + - `-i, --input <INPUT>` - Input MLF files (glob patterns supported, can be specified multiple times) 109 109 + - `-o, --output <OUTPUT>` - Output directory (required) 110 110 + - `--flat` - Use flat file structure 111 111 + 112 112 + **Available Generators:** 113 113 + 114 114 + | Generator | Output | Features | 115 115 + |-----------|--------|----------| 116 116 + | `json` | `.json` | AT Protocol JSON lexicons (always available) | 117 117 + | `typescript` | `.ts` | TypeScript interfaces with JSDoc, optional fields with `?` | 118 118 + | `go` | `.go` | Go structs with JSON tags, proper capitalization | 119 119 + | `rust` | `.rs` | Rust structs with serde, `Option<T>` for optional fields | 120 120 + 121 121 + ### TypeScript Example 122 122 + 123 123 + ```bash 124 124 + mlf generate code -g typescript -i thread.mlf -o src/types/ 125 125 + ``` 126 126 + 127 127 + **Input MLF:** 128 128 + ```mlf 129 129 + /// A discussion thread 130 130 + record main { 131 131 + /// Thread title 132 132 + title!: string constrained { 133 133 + maxLength: 200, 134 134 + }, 135 135 + /// Creation timestamp 136 136 + createdAt!: Datetime, 137 137 + posts: Post[], 138 138 + }; 139 139 + ``` 140 140 + 141 141 + **Generated TypeScript:** 142 142 + ```typescript 143 143 + /** 144 144 + * Generated from com.example.thread 145 145 + * Do not edit manually 146 146 + */ 147 147 + 148 148 + /** 149 149 + * A discussion thread 150 150 + */ 151 151 + export interface Main { 152 152 + /** Thread title */ 153 153 + title: string; 154 154 + /** Creation timestamp */ 155 155 + createdAt: string; 156 156 + posts?: Post[]; 157 157 + } 158 158 + ``` 159 159 + 160 160 + ### Go Example 161 161 + 162 162 + ```bash 163 163 + mlf generate code -g go -i thread.mlf -o pkg/models/ 164 164 + ``` 165 165 + 166 166 + **Generated Go:** 167 167 + ```go 168 168 + // Generated from com.example.thread 169 169 + // Do not edit manually 170 170 + 171 171 + package thread 172 172 + 173 173 + // Main represents a discussion thread 174 174 + type Main struct { 175 175 + // Thread title 176 176 + Title string `json:"title"` 177 177 + // Creation timestamp 178 178 + CreatedAt string `json:"createdAt"` 179 179 + // Posts (optional) 180 180 + Posts []Post `json:"posts,omitempty"` 181 181 + } 182 182 + ``` 183 183 + 184 184 + ### Rust Example 185 185 + 186 186 + ```bash 187 187 + mlf generate code -g rust -i thread.mlf -o src/models/ 188 188 + ``` 189 189 + 190 190 + **Generated Rust:** 191 191 + ```rust 192 192 + // Generated from com.example.thread 193 193 + // Do not edit manually 194 194 + 195 195 + use serde::{Deserialize, Serialize}; 196 196 + 197 197 + /// A discussion thread 198 198 + #[derive(Debug, Clone, Serialize, Deserialize)] 199 199 + pub struct Main { 200 200 + /// Thread title 201 201 + pub title: String, 202 202 + /// Creation timestamp 203 203 + #[serde(rename = "createdAt")] 204 204 + pub created_at: String, 205 205 + /// Posts (optional) 206 206 + #[serde(skip_serializing_if = "Option::is_none")] 207 207 + pub posts: Option<Vec<Post>>, 208 208 + } 209 209 + ``` 210 210 + 211 211 + --- 212 212 + 213 213 + ## Generate MLF 214 214 + 215 215 + Convert ATProto JSON lexicons back to MLF format. 216 216 + 217 217 + ```bash 218 218 + mlf generate mlf -i <INPUT> -o <OUTPUT> 219 219 + ``` 220 220 + 221 221 + **Options:** 222 222 + - `-i, --input <INPUT>` - Input JSON lexicon files (glob patterns supported, can be specified multiple times) 223 223 + - `-o, --output <OUTPUT>` - Output directory (required) 224 224 + 225 225 + **Examples:** 226 226 + 227 227 + ```bash 228 228 + # Convert a single JSON lexicon to MLF 229 229 + mlf generate mlf -i com.example.thread.json -o ./lexicons/ 230 230 + # Creates: lexicons/com/example/thread.mlf 231 231 + 232 232 + # Convert multiple JSON lexicons 233 233 + mlf generate mlf -i lexicon1.json -i lexicon2.json -o ./mlf/ 234 234 + 235 235 + # Convert using glob pattern 236 236 + mlf generate mlf -i "dist/lexicons/**/*.json" -o ./src/ 237 237 + ``` 238 238 + 239 239 + **Features:** 240 240 + 241 241 + - **Smart type conversion** - Automatically converts format strings to prelude types 242 242 + - `"format": "did"` → `Did` 243 243 + - `"format": "datetime"` → `Datetime` 244 244 + - `"format": "handle"` → `Handle` 245 245 + - **Proper formatting** - Generates clean, properly indented MLF 246 246 + - **Reference conversion** - Converts `namespace#name` to `namespace.name` 247 247 + - **Complete coverage** - Supports all ATProto lexicon types 248 248 + 249 249 + **Input JSON:** 250 250 + ```json 251 251 + { 252 252 + "lexicon": 1, 253 253 + "id": "com.example.thread", 254 254 + "defs": { 255 255 + "main": { 256 256 + "type": "record", 257 257 + "record": { 258 258 + "type": "object", 259 259 + "required": ["title", "createdAt"], 260 260 + "properties": { 261 261 + "title": { 262 262 + "type": "string", 263 263 + "maxLength": 200 264 264 + }, 265 265 + "createdAt": { 266 266 + "type": "string", 267 267 + "format": "datetime" 268 268 + } 269 269 + } 270 270 + } 271 271 + } 272 272 + } 273 273 + } 274 274 + ``` 275 275 + 276 276 + **Generated MLF:** 277 277 + ```mlf 278 278 + record main { 279 279 + title!: string constrained { 280 280 + maxLength: 200, 281 281 + }, 282 282 + createdAt!: Datetime, 283 283 + }; 284 284 + ``` 285 285 + 286 286 + --- 287 287 + 288 288 + ## Code Generator Features 289 289 + 290 290 + ### Documentation Comments 291 291 + 292 292 + All generators preserve documentation comments from MLF: 293 293 + 294 294 + ```mlf 295 295 + /// This is a user profile 296 296 + def Profile = { 297 297 + /// The user's display name 298 298 + displayName: string, 299 299 + }; 300 300 + ``` 301 301 + 302 302 + Generates appropriate doc comments for each language (JSDoc, Go comments, Rust doc comments). 303 303 + 304 304 + ### Optional Fields 305 305 + 306 306 + Optional fields are handled idiomatically in each language: 307 307 + 308 308 + - **TypeScript**: `field?: Type` 309 309 + - **Go**: `Field *Type` or `json:",omitempty"` 310 310 + - **Rust**: `field: Option<Type>` with `#[serde(skip_serializing_if = "Option::is_none")]` 311 311 + 312 312 + ### Field Naming Conventions 313 313 + 314 314 + Each generator follows language conventions: 315 315 + 316 316 + - **TypeScript**: camelCase (matches JSON) 317 317 + - **Go**: PascalCase with JSON tags 318 318 + - **Rust**: snake_case with `#[serde(rename)]` attributes 319 319 + 320 320 + ### Type Mapping 321 321 + 322 322 + MLF types are mapped to appropriate language types: 323 323 + 324 324 + | MLF Type | TypeScript | Go | Rust | 325 325 + |----------|------------|-------|------| 326 326 + | `string` | `string` | `string` | `String` | 327 327 + | `integer` | `number` | `int64` | `i64` | 328 328 + | `boolean` | `boolean` | `bool` | `bool` | 329 329 + | `bytes` | `Uint8Array` | `[]byte` | `Vec<u8>` | 330 330 + | `array` | `T[]` | `[]T` | `Vec<T>` | 331 331 + | `Did` | `string` | `string` | `String` | 332 332 + | `Datetime` | `string` | `string` | `String` | 333 333 + 334 334 + --- 335 335 + 336 336 + ## Tips 337 337 + 338 338 + 1. **Use configuration** - Set up `mlf.toml` for multi-output generation 339 339 + 2. **Commit generated code** - If it's part of your build artifacts 340 340 + 3. **Regenerate often** - Run `mlf generate` after any lexicon changes 341 341 + 4. **Use flat mode** - For simpler directory structures 342 342 + 5. **Multiple generators** - Generate multiple languages from the same MLF files 343 343 + 6. **Version control** - Track both MLF source and generated code 344 344 + 345 345 + ## Error Handling 346 346 + 347 347 + If generation fails for some files, you'll see detailed errors: 348 348 + 349 349 + ``` 350 350 + 3 file(s) generated successfully, 1 error(s) encountered: 351 351 + 352 352 + thread.mlf - Type resolution error: undefined reference to 'Post' 353 353 + ``` 354 354 + 355 355 + The command exits with status `1` if any errors occur.

+307

website/content/docs/cli/06-fetch.md

reviewed

··· 1 1 + +++ 2 2 + title = "Fetch Command" 3 3 + description = "Download lexicons from remote repositories" 4 4 + weight = 6 5 5 + +++ 6 6 + 7 7 + The `mlf fetch` command downloads ATProto lexicons from remote repositories and converts them to MLF format. 8 8 + 9 9 + ## Usage 10 10 + 11 11 + ```bash 12 12 + # Fetch all dependencies from mlf.toml 13 13 + mlf fetch 14 14 + 15 15 + # Fetch a specific namespace 16 16 + mlf fetch <NAMESPACE> 17 17 + 18 18 + # Fetch and save to dependencies 19 19 + mlf fetch <NAMESPACE> --save 20 20 + ``` 21 21 + 22 22 + **Arguments:** 23 23 + - `[NAMESPACE]` - Optional namespace to fetch (e.g., `stream.place`, `app.bsky`) 24 24 + 25 25 + **Options:** 26 26 + - `--save` - Add the namespace to dependencies in `mlf.toml` 27 27 + 28 28 + ## How It Works 29 29 + 30 30 + The fetch command follows the ATProto lexicon discovery protocol: 31 31 + 32 32 + 1. **DNS Lookup** - Queries `_lexicon.<reversed-authority>` TXT record 33 33 + 2. **DID Resolution** - Resolves the DID to a PDS endpoint 34 34 + 3. **Fetch Records** - Queries `com.atproto.repo.listRecords` for lexicon schemas 35 35 + 4. **Save & Convert** - Saves JSON and converts to MLF format 36 36 + 37 37 + ## Examples 38 38 + 39 39 + ### Fetch All Dependencies 40 40 + 41 41 + With an `mlf.toml` file: 42 42 + 43 43 + ```toml 44 44 + [dependencies] 45 45 + dependencies = ["stream.place", "app.bsky"] 46 46 + ``` 47 47 + 48 48 + Run: 49 49 + 50 50 + ```bash 51 51 + mlf fetch 52 52 + ``` 53 53 + 54 54 + **Output:** 55 55 + ``` 56 56 + Fetching 2 dependencies... 57 57 + 58 58 + Fetching: stream.place 59 59 + Fetching lexicons for authority: stream.place 60 60 + → Resolved DID: did:web:stream.place 61 61 + → Using PDS: https://stream.place 62 62 + → Found 5 lexicon record(s) 63 63 + Processing: stream.place.thread 64 64 + → Saved JSON to .mlf/lexicons/json/stream.place.thread.json 65 65 + → Converted to MLF at .mlf/lexicons/mlf/stream.place.thread.mlf 66 66 + ✓ Successfully fetched lexicons for stream.place 67 67 + 68 68 + Fetching: app.bsky 69 69 + ... 70 70 + 71 71 + ✓ Successfully fetched all 2 dependencies 72 72 + ``` 73 73 + 74 74 + ### Fetch Specific Namespace 75 75 + 76 76 + ```bash 77 77 + mlf fetch stream.place 78 78 + ``` 79 79 + 80 80 + This downloads all lexicons under the `stream.place` authority. 81 81 + 82 82 + ### Fetch and Save 83 83 + 84 84 + ```bash 85 85 + mlf fetch stream.place --save 86 86 + ``` 87 87 + 88 88 + This: 89 89 + 1. Downloads the lexicons 90 90 + 2. Adds `"stream.place"` to the dependencies array in `mlf.toml` 91 91 + 3. Creates `mlf.toml` if it doesn't exist 92 92 + 93 93 + ## Storage Structure 94 94 + 95 95 + Fetched lexicons are stored in `.mlf/lexicons/`: 96 96 + 97 97 + ``` 98 98 + .mlf/ 99 99 + ├── .gitignore # Auto-generated 100 100 + ├── .lexicon-cache.toml # Cache metadata 101 101 + └── lexicons/ 102 102 + ├── json/ # Original JSON lexicons 103 103 + │ ├── stream.place.thread.json 104 104 + │ └── app.bsky.actor.profile.json 105 105 + └── mlf/ # Converted MLF format 106 106 + ├── stream.place.thread.mlf 107 107 + └── app.bsky.actor.profile.mlf 108 108 + ``` 109 109 + 110 110 + ### Cache File 111 111 + 112 112 + The `.lexicon-cache.toml` tracks what's been fetched: 113 113 + 114 114 + ```toml 115 115 + [[lexicons.stream.place.thread]] 116 116 + nsid = "stream.place.thread" 117 117 + fetched_at = "2024-01-15T10:30:00Z" 118 118 + did = "did:web:stream.place" 119 119 + ``` 120 120 + 121 121 + ## DNS Resolution 122 122 + 123 123 + For a namespace like `stream.place.thread`: 124 124 + 125 125 + 1. Extract authority: `stream.place` 126 126 + 2. Reverse for DNS: `place.stream` 127 127 + 3. Query TXT record: `_lexicon.place.stream` 128 128 + 4. Parse `did=did:web:...` or `did=did:plc:...` 129 129 + 130 130 + **Example DNS record:** 131 131 + ``` 132 132 + _lexicon.place.stream. 300 IN TXT "did=did:web:stream.place" 133 133 + ``` 134 134 + 135 135 + ## DID Resolution 136 136 + 137 137 + ### did:web 138 138 + 139 139 + For `did:web:stream.place`, the PDS is `https://stream.place` 140 140 + 141 141 + ### did:plc 142 142 + 143 143 + For `did:plc:abc123...`, query `https://plc.directory/did:plc:abc123...` to get the PDS endpoint from the DID document. 144 144 + 145 145 + ## Fetched Lexicons in Your Code 146 146 + 147 147 + Once fetched, lexicons in `.mlf/lexicons/mlf/` are automatically available for: 148 148 + 149 149 + ### Type References 150 150 + 151 151 + ```mlf 152 152 + use stream.place.thread; 153 153 + 154 154 + def Reply = { 155 155 + thread!: stream.place.thread, 156 156 + text!: string, 157 157 + }; 158 158 + ``` 159 159 + 160 160 + ### Code Generation 161 161 + 162 162 + ```bash 163 163 + mlf generate code -g typescript -i my-lexicon.mlf -o src/types/ 164 164 + ``` 165 165 + 166 166 + The generator can resolve references to fetched lexicons. 167 167 + 168 168 + ### Validation 169 169 + 170 170 + ```bash 171 171 + mlf check my-lexicon.mlf 172 172 + ``` 173 173 + 174 174 + The check command loads fetched lexicons for type resolution. 175 175 + 176 176 + ## Working Without mlf.toml 177 177 + 178 178 + If you don't have an `mlf.toml`, the fetch command will offer to create one: 179 179 + 180 180 + ```bash 181 181 + $ mlf fetch stream.place 182 182 + No mlf.toml found in current or parent directories. 183 183 + Would you like to create one in the current directory? (y/n) 184 184 + y 185 185 + Created mlf.toml in /path/to/current/dir 186 186 + ... 187 187 + ``` 188 188 + 189 189 + ## Re-fetching 190 190 + 191 191 + If a namespace is already cached, fetch skips it: 192 192 + 193 193 + ```bash 194 194 + $ mlf fetch stream.place 195 195 + Lexicon 'stream.place.thread' is already cached. Skipping fetch. 196 196 + (Use --force to re-fetch) 197 197 + ``` 198 198 + 199 199 + To re-fetch: 200 200 + 201 201 + ```bash 202 202 + mlf fetch stream.place --force # Not yet implemented 203 203 + ``` 204 204 + 205 205 + ## Error Handling 206 206 + 207 207 + ### DNS Errors 208 208 + 209 209 + ``` 210 210 + ✗ DNS lookup failed: No TXT record found for _lexicon.place.stream 211 211 + ``` 212 212 + 213 213 + **Causes:** 214 214 + - Domain doesn't have a lexicon TXT record 215 215 + - DNS propagation delay 216 216 + - Network issues 217 217 + 218 218 + ### DID Resolution Errors 219 219 + 220 220 + ``` 221 221 + ✗ Failed to resolve DID: No PDS endpoint found in DID document 222 222 + ``` 223 223 + 224 224 + **Causes:** 225 225 + - Invalid DID format 226 226 + - PLC directory unreachable 227 227 + - DID document missing PDS service 228 228 + 229 229 + ### No Records Found 230 230 + 231 231 + ``` 232 232 + ✗ No lexicon records found for stream.place 233 233 + ``` 234 234 + 235 235 + **Causes:** 236 236 + - Namespace exists but has no published lexicons 237 237 + - Wrong namespace (typo) 238 238 + - PDS doesn't support lexicon publishing 239 239 + 240 240 + ## Best Practices 241 241 + 242 242 + 1. **Fetch before work** - Always fetch dependencies before coding 243 243 + 2. **Use --save** - Keep `mlf.toml` up to date with dependencies 244 244 + 3. **Don't commit `.mlf/`** - Let each developer fetch independently 245 245 + 4. **Check DNS** - Verify TXT records before fetching 246 246 + 5. **Version dependencies** - Consider tracking lexicon versions (future feature) 247 247 + 248 248 + ## CI/CD Integration 249 249 + 250 250 + In your CI pipeline: 251 251 + 252 252 + ```yaml 253 253 + # GitHub Actions example 254 254 + - name: Fetch ATProto Lexicons 255 255 + run: | 256 256 + mlf fetch 257 257 + 258 258 + - name: Generate Code 259 259 + run: | 260 260 + mlf generate 261 261 + ``` 262 262 + 263 263 + This ensures builds have access to the latest lexicons. 264 264 + 265 265 + ## Comparison with npm/cargo 266 266 + 267 267 + The fetch command is similar to package managers: 268 268 + 269 269 + | Command | npm | cargo | mlf | 270 270 + |---------|-----|-------|-----| 271 271 + | Install deps | `npm install` | `cargo fetch` | `mlf fetch` | 272 272 + | Add dep | `npm install pkg --save` | `cargo add pkg` | `mlf fetch ns --save` | 273 273 + | Config file | `package.json` | `Cargo.toml` | `mlf.toml` | 274 274 + | Cache | `node_modules/` | `~/.cargo/` | `.mlf/` | 275 275 + 276 276 + ## Troubleshooting 277 277 + 278 278 + ### Network Issues 279 279 + 280 280 + ```bash 281 281 + # Check DNS resolution 282 282 + dig TXT _lexicon.place.stream 283 283 + 284 284 + # Test DID resolution 285 285 + curl https://plc.directory/did:plc:abc123 286 286 + ``` 287 287 + 288 288 + ### Invalid Namespace 289 289 + 290 290 + Make sure you're using the correct namespace format: 291 291 + - ✓ `stream.place` 292 292 + - ✓ `app.bsky` 293 293 + - ✗ `stream.place.thread` (too specific) 294 294 + 295 295 + ### Permission Errors 296 296 + 297 297 + Ensure you have write permissions for the project directory to create `.mlf/`. 298 298 + 299 299 + ## Future Features 300 300 + 301 301 + Planned enhancements: 302 302 + 303 303 + - `--force` flag to re-fetch cached lexicons 304 304 + - Version pinning (fetch specific lexicon versions) 305 305 + - Private/authenticated repositories 306 306 + - Offline mode with local cache 307 307 + - Fetch from local directories

+335

website/content/docs/cli/07-errors.md

reviewed

··· 1 1 + +++ 2 2 + title = "Error Messages" 3 3 + description = "Understanding MLF error diagnostics" 4 4 + weight = 7 5 5 + +++ 6 6 + 7 7 + MLF provides rich, helpful error messages with source code context and suggestions for fixing issues. 8 8 + 9 9 + ## Error Format 10 10 + 11 11 + All MLF errors follow this format: 12 12 + 13 13 + ``` 14 14 + × Error title 15 15 + ╭─[file.mlf:5:12] 16 16 + 5 │ author: ProfileView, 17 17 + · ^^^^^^^^^^^ error message 18 18 + ╰──── 19 19 + help: Suggestion for fixing the issue 20 20 + ``` 21 21 + 22 22 + **Components:** 23 23 + - **× Error title** - Brief description of the error 24 24 + - **Source location** - File name, line, and column 25 25 + - **Source context** - The relevant code snippet 26 26 + - **Error span** - Highlighted location with `^^^` 27 27 + - **help:** - Actionable suggestion for fixing 28 28 + 29 29 + ## Common Errors 30 30 + 31 31 + ### Parse Errors 32 32 + 33 33 + #### Expected Token 34 34 + 35 35 + ``` 36 36 + × Expected '}', found ',' 37 37 + ╭─[thread.mlf:10:5] 38 38 + 10 │ title: string, 39 39 + · ^ expected '}' 40 40 + ╰──── 41 41 + help: Check for missing closing braces or extra commas 42 42 + ``` 43 43 + 44 44 + **Cause:** Syntax error in MLF code 45 45 + 46 46 + **Fix:** Correct the syntax according to MLF grammar 47 47 + 48 48 + #### Invalid Identifier 49 49 + 50 50 + ``` 51 51 + × Invalid identifier: '123invalid' 52 52 + ╭─[thread.mlf:5:5] 53 53 + 5 │ 123invalid: string, 54 54 + · ^^^^^^^^^^ identifiers cannot start with numbers 55 55 + ╰──── 56 56 + help: Identifiers must start with a letter or underscore 57 57 + ``` 58 58 + 59 59 + **Cause:** Identifier doesn't follow naming rules 60 60 + 61 61 + **Fix:** Start identifiers with letters or underscores 62 62 + 63 63 + ### Type Errors 64 64 + 65 65 + #### Undefined Reference 66 66 + 67 67 + ``` 68 68 + × Undefined reference to 'ProfileView' 69 69 + ╭─[thread.mlf:8:12] 70 70 + 8 │ author: ProfileView, 71 71 + · ^^^^^^^^^^^ 'ProfileView' is not defined 72 72 + ╰──── 73 73 + help: Make sure this type is defined in the same file or imported via 'use'. 74 74 + ``` 75 75 + 76 76 + **Causes:** 77 77 + - Type is not defined 78 78 + - Type is in another file and not imported 79 79 + - Typo in type name 80 80 + 81 81 + **Fixes:** 82 82 + - Define the type in the same file 83 83 + - Use `mlf fetch` to download external lexicons 84 84 + - Add a `use` statement (if MLF supports imports) 85 85 + - Check spelling 86 86 + 87 87 + #### Type Mismatch 88 88 + 89 89 + ``` 90 90 + × Type mismatch: expected integer, found string 91 91 + ╭─[thread.mlf:12:15] 92 92 + 12 │ count: string, 93 93 + · ^^^^^^ expected integer type 94 94 + ╰──── 95 95 + help: Change this to 'integer' or update the constraint 96 96 + ``` 97 97 + 98 98 + **Cause:** Field type doesn't match its definition 99 99 + 100 100 + **Fix:** Update the type to match the schema 101 101 + 102 102 + ### Constraint Errors 103 103 + 104 104 + #### Invalid Constraint 105 105 + 106 106 + ``` 107 107 + × Invalid constraint for type 'integer': 'maxLength' 108 108 + ╭─[thread.mlf:15:9] 109 109 + 15 │ maxLength: 100, 110 110 + · ^^^^^^^^^ 'maxLength' is only valid for string types 111 111 + ╰──── 112 112 + help: Use 'maximum' for integer constraints 113 113 + ``` 114 114 + 115 115 + **Cause:** Constraint doesn't apply to the type 116 116 + 117 117 + **Fix:** Use the correct constraint for the type: 118 118 + - String: `maxLength`, `minLength`, `maxGraphemes`, `minGraphemes` 119 119 + - Integer: `minimum`, `maximum` 120 120 + - Array: `maxLength`, `minLength` 121 121 + 122 122 + #### Constraint Value Error 123 123 + 124 124 + ``` 125 125 + × Constraint value must be positive 126 126 + ╭─[thread.mlf:18:20] 127 127 + 18 │ maxLength: -10, 128 128 + · ^^^ negative value not allowed 129 129 + ╰──── 130 130 + help: Use a positive integer value 131 131 + ``` 132 132 + 133 133 + **Cause:** Constraint value is invalid 134 134 + 135 135 + **Fix:** Use a valid value according to the constraint rules 136 136 + 137 137 + ### Record Errors 138 138 + 139 139 + #### Missing Record Key 140 140 + 141 141 + ``` 142 142 + × Record definition must specify a key type 143 143 + ╭─[thread.mlf:3:1] 144 144 + 3 │ record main { 145 145 + · ^^^^^^^^^^^ missing key specification 146 146 + ╰──── 147 147 + help: Add 'key: "tid"' or another valid key type to the record 148 148 + ``` 149 149 + 150 150 + **Cause:** Record doesn't specify how records are keyed 151 151 + 152 152 + **Fix:** Add a key specification to the record definition 153 153 + 154 154 + ### XRPC Errors 155 155 + 156 156 + #### Invalid Response Code 157 157 + 158 158 + ``` 159 159 + × Invalid HTTP response code: 999 160 160 + ╭─[api.mlf:25:5] 161 161 + 25 │ 999: error, 162 162 + · ^^^ response code must be between 200-599 163 163 + ╰──── 164 164 + help: Use a valid HTTP status code 165 165 + ``` 166 166 + 167 167 + **Cause:** Invalid HTTP status code in query/procedure 168 168 + 169 169 + **Fix:** Use standard HTTP status codes (200, 400, 401, 404, 500, etc.) 170 170 + 171 171 + #### Missing Required Response 172 172 + 173 173 + ``` 174 174 + × Query/procedure must define at least one success response 175 175 + ╭─[api.mlf:20:1] 176 176 + 20 │ query getProfile(...) { 177 177 + · ^^^^^^^^^^^^^^^^^^^^^ no 200-level responses defined 178 178 + ╰──── 179 179 + help: Add at least one 2xx response (typically 200) 180 180 + ``` 181 181 + 182 182 + **Cause:** XRPC method has no success responses 183 183 + 184 184 + **Fix:** Add a 200-level response 185 185 + 186 186 + ### Union Errors 187 187 + 188 188 + #### Empty Union 189 189 + 190 190 + ``` 191 191 + × Union must have at least one type 192 192 + ╭─[thread.mlf:30:15] 193 193 + 30 │ data: unit | , 194 194 + · ^ empty union 195 195 + ╰──── 196 196 + help: Add at least one type to the union 197 197 + ``` 198 198 + 199 199 + **Cause:** Union has no types 200 200 + 201 201 + **Fix:** Add types to the union: `string | integer` 202 202 + 203 203 + #### Duplicate Union Types 204 204 + 205 205 + ``` 206 206 + × Duplicate type in union: 'string' 207 207 + ╭─[thread.mlf:32:20] 208 208 + 32 │ data: string | string, 209 209 + · ^^^^^^ duplicate type 210 210 + ╰──── 211 211 + help: Remove duplicate types from the union 212 212 + ``` 213 213 + 214 214 + **Cause:** Same type appears multiple times in union 215 215 + 216 216 + **Fix:** Remove duplicates 217 217 + 218 218 + ## Validation Errors 219 219 + 220 220 + ### Record Validation 221 221 + 222 222 + ``` 223 223 + ✗ Record validation failed with 2 error(s): 224 224 + • Field 'title' is required but missing 225 225 + • Field 'count': expected integer, found "123" 226 226 + ``` 227 227 + 228 228 + **Cause:** JSON record doesn't match lexicon schema 229 229 + 230 230 + **Fix:** Update the JSON to match the schema 231 231 + 232 232 + ## Generation Errors 233 233 + 234 234 + ### File Read Error 235 235 + 236 236 + ``` 237 237 + Failed to read file: permission denied 238 238 + ``` 239 239 + 240 240 + **Cause:** Cannot read input file 241 241 + 242 242 + **Fix:** Check file permissions and path 243 243 + 244 244 + ### Type Resolution Error 245 245 + 246 246 + ``` 247 247 + Type resolution error: circular reference detected 248 248 + ``` 249 249 + 250 250 + **Cause:** Types reference each other in a cycle 251 251 + 252 252 + **Fix:** Break the circular dependency 253 253 + 254 254 + ### Code Generation Error 255 255 + 256 256 + ``` 257 257 + Generator 'typescript' not found 258 258 + ``` 259 259 + 260 260 + **Cause:** Generator feature not enabled 261 261 + 262 262 + **Fix:** Install with `--features typescript` or use `--all-features` 263 263 + 264 264 + ## Fetch Errors 265 265 + 266 266 + ### DNS Error 267 267 + 268 268 + ``` 269 269 + ✗ DNS lookup failed: No TXT record found for _lexicon.place.stream 270 270 + ``` 271 271 + 272 272 + **Cause:** Domain has no lexicon TXT record 273 273 + 274 274 + **Fix:** Verify the namespace is correct and has published lexicons 275 275 + 276 276 + ### Network Error 277 277 + 278 278 + ``` 279 279 + ✗ Failed to fetch lexicon records: connection timeout 280 280 + ``` 281 281 + 282 282 + **Cause:** Network connectivity issues 283 283 + 284 284 + **Fix:** Check internet connection and try again 285 285 + 286 286 + ### Parse Error 287 287 + 288 288 + ``` 289 289 + ✗ Failed to parse lexicon JSON: unexpected end of input 290 290 + ``` 291 291 + 292 292 + **Cause:** Malformed JSON from remote repository 293 293 + 294 294 + **Fix:** Report issue to namespace maintainer 295 295 + 296 296 + ## Exit Codes 297 297 + 298 298 + All MLF commands use standard exit codes: 299 299 + 300 300 + - `0` - Success 301 301 + - `1` - Error occurred 302 302 + 303 303 + Use in scripts: 304 304 + 305 305 + ```bash 306 306 + if mlf check; then 307 307 + echo "✓ Valid" 308 308 + else 309 309 + echo "✗ Invalid" 310 310 + exit 1 311 311 + fi 312 312 + ``` 313 313 + 314 314 + ## Tips for Reading Errors 315 315 + 316 316 + 1. **Read the title** - Gives you the high-level issue 317 317 + 2. **Check the location** - Find the exact line and column 318 318 + 3. **Examine the span** - See what code is problematic 319 319 + 4. **Follow the help** - Actionable suggestions for fixes 320 320 + 5. **Look for patterns** - Similar errors often have similar fixes 321 321 + 322 322 + ## Reporting Bugs 323 323 + 324 324 + If you encounter an error that seems like a bug: 325 325 + 326 326 + 1. Note the exact error message 327 327 + 2. Create a minimal reproduction case 328 328 + 3. Check if it's a known issue 329 329 + 4. Report at: https://github.com/anthropics/claude-code/issues 330 330 + 331 331 + Include: 332 332 + - MLF version (`mlf --version`) 333 333 + - Complete error message 334 334 + - Minimal MLF code that reproduces the issue 335 335 + - Expected behavior vs actual behavior

+60

website/content/docs/cli/_index.md

reviewed

··· 1 1 + +++ 2 2 + title = "CLI Reference" 3 3 + description = "Command-line tool documentation" 4 4 + weight = 3 5 5 + sort_by = "weight" 6 6 + template = "section.html" 7 7 + +++ 8 8 + 9 9 + The MLF CLI is a powerful command-line tool for working with Matt's Lexicon Format and ATProto lexicons. 10 10 + 11 11 + ## Overview 12 12 + 13 13 + The `mlf` command-line tool provides: 14 14 + 15 15 + - **Validation** - Check MLF files for syntax and type errors 16 16 + - **Code Generation** - Generate TypeScript, Go, Rust, and JSON from MLF 17 17 + - **Lexicon Fetching** - Download lexicons from remote ATProto repositories 18 18 + - **Format Conversion** - Convert between MLF and JSON lexicon formats 19 19 + - **Project Management** - Configure projects with `mlf.toml` 20 20 + 21 21 + ## Quick Start 22 22 + 23 23 + ```bash 24 24 + # Check MLF files 25 25 + mlf check 26 26 + 27 27 + # Generate TypeScript types 28 28 + mlf generate code -g typescript -i "lexicons/**/*.mlf" -o src/types/ 29 29 + 30 30 + # Fetch remote lexicons 31 31 + mlf fetch stream.place --save 32 32 + 33 33 + # Generate all configured outputs 34 34 + mlf generate 35 35 + ``` 36 36 + 37 37 + ## Project Configuration 38 38 + 39 39 + Projects can be configured with an `mlf.toml` file that specifies source directories, output configurations, and dependencies. This allows you to run commands without repeatedly specifying arguments. 40 40 + 41 41 + See the [Configuration](02-configuration.md) section for details. 42 42 + 43 43 + ## Command Categories 44 44 + 45 45 + ### Validation Commands 46 46 + - `mlf check` - Validate MLF syntax and types 47 47 + - `mlf validate` - Validate JSON records against lexicons 48 48 + 49 49 + ### Generation Commands 50 50 + - `mlf generate lexicon` - Generate JSON lexicons 51 51 + - `mlf generate code` - Generate code in various languages 52 52 + - `mlf generate mlf` - Convert JSON lexicons to MLF 53 53 + - `mlf generate` (no subcommand) - Generate all configured outputs 54 54 + 55 55 + ### Fetching Commands 56 56 + - `mlf fetch` - Download lexicons from remote repositories 57 57 + - `mlf fetch <namespace>` - Fetch specific namespace 58 58 + - `mlf fetch <namespace> --save` - Fetch and add to dependencies 59 59 + 60 60 + This guide walks through each command in detail, with examples and usage patterns.