add cli check command

README.md

···
 - ✅ **Circular Dependency Detection**: prevents infinite reference loops
 - ✅ **Detailed Error Messages**: validation errors with path information
 
+## CLI Usage
+
+Validate lexicon files from the command line:
+
+```sh
+# Validate a single file
+gleam run -m honk check ./lexicons/xyz/statusphere/status.json
+
+# Validate all .json files in a directory
+gleam run -m honk check ./lexicons/
+
+# Show help
+gleam run -m honk help
+```
+
+When validating a directory, all lexicons are loaded together to resolve cross-lexicon references
+
 ## API Overview
 
 ### Main Functions

gleam.toml

···
 gleam_json = ">= 3.0.0 and < 4.0.0"
 gleam_regexp = ">= 1.0.0 and < 2.0.0"
 gleam_time = ">= 1.5.0 and < 2.0.0"
+simplifile = ">= 2.3.1 and < 3.0.0"
+argv = ">= 1.0.2 and < 2.0.0"
 
 [dev-dependencies]
 gleeunit = ">= 1.0.0 and < 2.0.0"

manifest.toml

···
 # You typically do not need to edit this file
 
 packages = [
+  { name = "argv", version = "1.0.2", build_tools = ["gleam"], requirements = [], otp_app = "argv", source = "hex", outer_checksum = "BA1FF0929525DEBA1CE67256E5ADF77A7CDDFE729E3E3F57A5BDCAA031DED09D" },
+  { name = "filepath", version = "1.1.2", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "filepath", source = "hex", outer_checksum = "B06A9AF0BF10E51401D64B98E4B627F1D2E48C154967DA7AF4D0914780A6D40A" },
   { name = "gleam_json", version = "3.1.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_json", source = "hex", outer_checksum = "44FDAA8847BE8FC48CA7A1C089706BD54BADCC4C45B237A992EDDF9F2CDB2836" },
   { name = "gleam_regexp", version = "1.1.1", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_regexp", source = "hex", outer_checksum = "9C215C6CA84A5B35BB934A9B61A9A306EC743153BE2B0425A0D032E477B062A9" },
   { name = "gleam_stdlib", version = "0.65.0", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "7C69C71D8C493AE11A5184828A77110EB05A7786EBF8B25B36A72F879C3EE107" },
   { name = "gleam_time", version = "1.5.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_time", source = "hex", outer_checksum = "D560E672C7279C89908981E068DF07FD16D0C859DCA266F908B18F04DF0EB8E6" },
   { name = "gleeunit", version = "1.9.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleeunit", source = "hex", outer_checksum = "DA9553CE58B67924B3C631F96FE3370C49EB6D6DC6B384EC4862CC4AAA718F3C" },
+  { name = "simplifile", version = "2.3.1", build_tools = ["gleam"], requirements = ["filepath", "gleam_stdlib"], otp_app = "simplifile", source = "hex", outer_checksum = "957E0E5B75927659F1D2A1B7B75D7B9BA96FAA8D0C53EA71C4AD9CD0C6B848F6" },
 ]
 
 [requirements]
+argv = { version = ">= 1.0.2 and < 2.0.0" }
 gleam_json = { version = ">= 3.0.0 and < 4.0.0" }
 gleam_regexp = { version = ">= 1.0.0 and < 2.0.0" }
 gleam_stdlib = { version = ">= 0.44.0 and < 2.0.0" }
 gleam_time = { version = ">= 1.5.0 and < 2.0.0" }
 gleeunit = { version = ">= 1.0.0 and < 2.0.0" }
+simplifile = { version = ">= 2.3.1 and < 3.0.0" }

src/honk.gleam

···
 // Main public API for the ATProtocol lexicon validator
 
+import argv
 import gleam/dict.{type Dict}
+import gleam/dynamic/decode
+import gleam/int
+import gleam/io
 import gleam/json.{type Json}
 import gleam/list
 import gleam/option.{None, Some}
 import gleam/result
+import gleam/string
 import honk/errors
 import honk/internal/json_helpers
 import honk/types
 import honk/validation/context
 import honk/validation/formats
+import simplifile
 
 // Import validators
 import honk/validation/field as validation_field
···
                       Ok(_) -> errors_acc
                       Error(e) -> {
                         // Include def name in error for better context
-                        let error_msg =
-                          lex_id
-                          <> "#"
-                          <> def_name
-                          <> ": "
-                          <> errors.to_string(e)
+                        // Extract just the message without wrapper text
+                        let message = case e {
+                          errors.InvalidSchema(msg) -> msg
+                          errors.DataValidation(msg) -> msg
+                          errors.LexiconNotFound(msg) -> "Lexicon not found: " <> msg
+                        }
+                        // Clean up leading ": " if present
+                        let clean_message = case string.starts_with(message, ": ") {
+                          True -> string.drop_start(message, 2)
+                          False -> message
+                        }
+                        let error_msg = lex_id <> "#" <> def_name <> ": " <> clean_message
                         case dict.get(errors_acc, lex_id) {
                           Ok(existing_errors) ->
                             dict.insert(errors_acc, lex_id, [
···
   }
 }
 
-/// Entry point for the honk lexicon validator.
+/// CLI entry point for the honk lexicon validator
 ///
-/// This function serves as an example entry point and can be used
-/// for basic CLI or testing purposes. For actual validation,
-/// use the `validate()` or `validate_record()` functions.
-///
-/// ## Example
-///
-/// ```gleam
-/// import honk
-///
-/// pub fn main() {
-///   honk.main()
-/// }
-/// ```
+/// Usage:
+///   gleam run -m honk check <path>
+///   gleam run -m honk help
 pub fn main() -> Nil {
-  // This would typically be called from tests or CLI
-  let _example_result = is_valid_nsid("com.example.record")
-  Nil
+  case argv.load().arguments {
+    ["check", path] -> validate_path(path)
+    ["help"] | [] -> show_help()
+    _ -> {
+      io.println_error("Unknown command. Use 'help' for usage information.")
+      Nil
+    }
+  }
+}
+
+/// Validate a path (auto-detects file or directory)
+fn validate_path(path: String) -> Nil {
+  case simplifile.is_file(path) {
+    Ok(True) -> validate_file(path)
+    Ok(False) ->
+      case simplifile.is_directory(path) {
+        Ok(True) -> validate_directory(path)
+        Ok(False) -> {
+          io.println_error("Error: Path is neither a file nor a directory: " <> path)
+          Nil
+        }
+        Error(_) -> {
+          io.println_error("Error: Cannot access path: " <> path)
+          Nil
+        }
+      }
+    Error(_) -> {
+      io.println_error("Error: Cannot access path: " <> path)
+      Nil
+    }
+  }
+}
+
+/// Validate a single lexicon file
+fn validate_file(file_path: String) -> Nil {
+  case read_and_validate_file(file_path) {
+    Ok(_) -> {
+      io.println("✓ " <> file_path <> " - valid")
+      Nil
+    }
+    Error(msg) -> {
+      io.println_error("✗ " <> file_path)
+      io.println_error("  " <> msg)
+      Nil
+    }
+  }
+}
+
+/// Validate all .json files in a directory
+fn validate_directory(dir_path: String) -> Nil {
+  case simplifile.get_files(dir_path) {
+    Error(_) -> {
+      io.println_error("Error: Cannot read directory: " <> dir_path)
+      Nil
+    }
+    Ok(all_files) -> {
+      // Filter for .json files
+      let json_files =
+        all_files
+        |> list.filter(fn(path) { string.ends_with(path, ".json") })
+
+      case json_files {
+        [] -> {
+          io.println("No .json files found in " <> dir_path)
+          Nil
+        }
+        files -> {
+          // Read and parse all files
+          let file_results =
+            files
+            |> list.map(fn(file) {
+              case read_json_file(file) {
+                Ok(json_value) -> #(file, Ok(json_value))
+                Error(msg) -> #(file, Error(msg))
+              }
+            })
+
+          // Separate successful parses from failures
+          let #(parse_errors, parsed_files) =
+            list.partition(file_results, fn(result) {
+              case result {
+                #(_, Error(_)) -> True
+                #(_, Ok(_)) -> False
+              }
+            })
+
+          // Display parse errors
+          parse_errors
+          |> list.each(fn(result) {
+            case result {
+              #(file, Error(msg)) -> {
+                io.println_error("✗ " <> file)
+                io.println_error("  " <> msg)
+              }
+              _ -> Nil
+            }
+          })
+
+          // Get all successfully parsed lexicons
+          let lexicons =
+            parsed_files
+            |> list.filter_map(fn(result) {
+              case result {
+                #(_, Ok(json)) -> Ok(json)
+                _ -> Error(Nil)
+              }
+            })
+
+          // Validate all lexicons together (allows cross-lexicon references)
+          case validate(lexicons) {
+            Ok(_) -> {
+              // All lexicons are valid
+              parsed_files
+              |> list.each(fn(result) {
+                case result {
+                  #(file, Ok(_)) -> io.println("✓ " <> file)
+                  _ -> Nil
+                }
+              })
+            }
+            Error(error_map) -> {
+              // Some lexicons have errors - map errors back to files
+              parsed_files
+              |> list.each(fn(result) {
+                case result {
+                  #(file, Ok(json)) -> {
+                    // Get the lexicon ID for this file
+                    case json_helpers.get_string(json, "id") {
+                      Some(lex_id) -> {
+                        case dict.get(error_map, lex_id) {
+                          Ok(errors) -> {
+                            io.println_error("✗ " <> file)
+                            errors
+                            |> list.each(fn(err) {
+                              io.println_error("  " <> err)
+                            })
+                          }
+                          Error(_) -> io.println("✓ " <> file)
+                        }
+                      }
+                      None -> {
+                        io.println_error("✗ " <> file)
+                        io.println_error("  Missing lexicon id")
+                      }
+                    }
+                  }
+                  _ -> Nil
+                }
+              })
+            }
+          }
+
+          // Summary
+          let total = list.length(files)
+          let parse_error_count = list.length(parse_errors)
+          let validation_error_count = case validate(lexicons) {
+            Ok(_) -> 0
+            Error(error_map) -> dict.size(error_map)
+          }
+          let total_errors = parse_error_count + validation_error_count
+
+          case total_errors {
+            0 ->
+              io.println(
+                "\nAll " <> int.to_string(total) <> " schemas validated successfully.",
+              )
+            _ ->
+              io.println_error(
+                "\n"
+                <> int.to_string(total_errors)
+                <> " of "
+                <> int.to_string(total)
+                <> " schemas failed validation.",
+              )
+          }
+
+          Nil
+        }
+      }
+    }
+  }
+}
+
+/// Read and parse a JSON file (without validation)
+fn read_json_file(file_path: String) -> Result(Json, String) {
+  use content <- result.try(
+    simplifile.read(file_path)
+    |> result.map_error(fn(_) { "Cannot read file" }),
+  )
+
+  use json_dynamic <- result.try(
+    json.parse(content, decode.dynamic)
+    |> result.map_error(fn(_) { "Invalid JSON" }),
+  )
+
+  json_helpers.dynamic_to_json(json_dynamic)
+  |> result.map_error(fn(_) { "Failed to convert JSON" })
+}
+
+/// Read a file and validate it as a lexicon
+fn read_and_validate_file(file_path: String) -> Result(Nil, String) {
+  use content <- result.try(
+    simplifile.read(file_path)
+    |> result.map_error(fn(_) { "Cannot read file" }),
+  )
+
+  use json_dynamic <- result.try(
+    json.parse(content, decode.dynamic)
+    |> result.map_error(fn(_) { "Invalid JSON" }),
+  )
+
+  use json_value <- result.try(
+    json_helpers.dynamic_to_json(json_dynamic)
+    |> result.map_error(fn(_) { "Failed to convert JSON" }),
+  )
+
+  use _ <- result.try(
+    validate([json_value])
+    |> result.map_error(fn(error_map) { format_validation_errors(error_map) }),
+  )
+
+  Ok(Nil)
+}
+
+/// Format validation errors from the error map
+fn format_validation_errors(error_map: Dict(String, List(String))) -> String {
+  error_map
+  |> dict.to_list
+  |> list.map(fn(entry) {
+    let #(_key, errors) = entry
+    string.join(errors, "\n  ")
+  })
+  |> string.join("\n  ")
+}
+
+/// Show help text
+fn show_help() -> Nil {
+  io.println(
+    "
+honk - ATProtocol Lexicon Validator
+
+USAGE:
+  gleam run -m honk check <path>
+  gleam run -m honk help
+
+COMMANDS:
+  check <path>     Check a lexicon file or directory
+                   - If <path> is a file: validates that single lexicon
+                   - If <path> is a directory: recursively validates all .json files
+
+  help            Show this help message
+
+EXAMPLES:
+  gleam run -m honk check ./lexicons/xyz/statusphere/status.json
+  gleam run -m honk check ./lexicons
+
+VALIDATION:
+  - Validates lexicon structure (id, defs)
+  - Validates ALL definitions in each lexicon
+  - Checks types, constraints, and references
+  - Reports errors with definition context (lex.id#defName)
+",
+  )
 }

src/honk/validation/field/reference.gleam

···
   use ref_str <- result.try(ref_value)
 
   // Validate reference syntax
-  validate_ref_syntax(ref_str, def_name)
+  use _ <- result.try(validate_ref_syntax(ref_str, def_name))
+
+  // Validate that the reference can be resolved (only for global refs with full context)
+  case string.starts_with(ref_str, "#") {
+    True -> Ok(Nil)  // Local ref - will be validated in same lexicon
+    False -> {
+      // Global ref - check it exists in catalog if we have a current lexicon
+      case context.current_lexicon_id(ctx) {
+        Some(lex_id) -> {
+          // We have a full validation context, so validate reference resolution
+          use resolved <- result.try(resolution.resolve_reference(
+            ref_str,
+            ctx,
+            lex_id,
+          ))
+
+          case resolved {
+            Some(_) -> Ok(Nil)
+            None ->
+              Error(errors.invalid_schema(
+                def_name <> ": reference not found: " <> ref_str,
+              ))
+          }
+        }
+        None -> {
+          // No current lexicon (e.g., unit test context)
+          // Just validate syntax, can't check if reference exists
+          Ok(Nil)
+        }
+      }
+    }
+  }
 }
 
 /// Validates data against the referenced schema

test/fixtures/com.atproto.repo.strongRef.json

···
+{
+  "lexicon": 1,
+  "id": "com.atproto.repo.strongRef",
+  "defs": {
+    "main": {
+      "type": "object",
+      "required": ["uri", "cid"],
+      "properties": {
+        "uri": {
+          "type": "string",
+          "format": "at-uri"
+        },
+        "cid": {
+          "type": "string",
+          "format": "cid"
+        }
+      }
+    }
+  }
+}

test/fixtures/com.example.post.json

···
+{
+  "lexicon": 1,
+  "id": "com.example.post",
+  "defs": {
+    "main": {
+      "type": "record",
+      "key": "tid",
+      "record": {
+        "type": "object",
+        "required": ["text", "createdAt"],
+        "properties": {
+          "text": {
+            "type": "string",
+            "maxLength": 300
+          },
+          "author": {
+            "type": "ref",
+            "ref": "com.example.user#profile"
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "datetime"
+          },
+          "reply": {
+            "type": "ref",
+            "ref": "#replyRef"
+          }
+        }
+      }
+    },
+    "replyRef": {
+      "type": "object",
+      "required": ["parent", "root"],
+      "properties": {
+        "parent": {
+          "type": "ref",
+          "ref": "com.atproto.repo.strongRef"
+        },
+        "root": {
+          "type": "ref",
+          "ref": "com.atproto.repo.strongRef"
+        }
+      }
+    }
+  }
+}

test/fixtures/com.example.user.json

···
+{
+  "lexicon": 1,
+  "id": "com.example.user",
+  "defs": {
+    "main": {
+      "type": "record",
+      "key": "tid",
+      "record": {
+        "type": "object",
+        "required": ["handle", "displayName"],
+        "properties": {
+          "handle": {
+            "type": "string",
+            "format": "handle"
+          },
+          "displayName": {
+            "type": "string",
+            "maxLength": 64
+          },
+          "bio": {
+            "type": "string",
+            "maxLength": 256
+          }
+        }
+      }
+    },
+    "profile": {
+      "type": "object",
+      "required": ["handle"],
+      "properties": {
+        "handle": {
+          "type": "string",
+          "format": "handle"
+        },
+        "displayName": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

test/fixtures/invalid-ref.json

···
+{
+  "lexicon": 1,
+  "id": "com.example.invalidref",
+  "defs": {
+    "main": {
+      "type": "record",
+      "key": "tid",
+      "record": {
+        "type": "object",
+        "properties": {
+          "brokenRef": {
+            "type": "ref",
+            "ref": "com.example.nonexistent#thing"
+          }
+        }
+      }
+    }
+  }
+}

test/fixtures/invalid.json

···
+{
+  "lexicon": 1,
+  "id": "com.example.invalid",
+  "defs": {
+    "main": {
+      "type": "record",
+      "key": "tid",
+      "record": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    "badDef": {
+      "type": "string",
+      "minLength": 10,
+      "maxLength": 5
+    }
+  }
+}

test/fixtures/valid.json

···
+{
+  "lexicon": 1,
+  "id": "xyz.statusphere.status",
+  "defs": {
+    "main": {
+      "type": "record",
+      "key": "tid",
+      "record": {
+        "type": "object",
+        "required": ["status", "createdAt"],
+        "properties": {
+          "status": {
+            "type": "string",
+            "minLength": 1,
+            "maxGraphemes": 1,
+            "maxLength": 32
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "datetime"
+          }
+        }
+      }
+    }
+  }
+}