{"id":42298846,"url":"https://github.com/flanksource/clicky","last_synced_at":"2026-06-14T14:00:36.436Z","repository":{"id":308955739,"uuid":"1030316874","full_name":"flanksource/clicky","owner":"flanksource","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-09T16:54:58.000Z","size":89236,"stargazers_count":0,"open_issues_count":32,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T18:23:30.123Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flanksource.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-01T12:40:51.000Z","updated_at":"2026-06-09T17:02:22.000Z","dependencies_parsed_at":"2026-02-23T09:04:55.720Z","dependency_job_id":null,"html_url":"https://github.com/flanksource/clicky","commit_stats":null,"previous_names":["flanksource/clicky"],"tags_count":50,"template":false,"template_full_name":null,"purl":"pkg:github/flanksource/clicky","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flanksource%2Fclicky","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flanksource%2Fclicky/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flanksource%2Fclicky/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flanksource%2Fclicky/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flanksource","download_url":"https://codeload.github.com/flanksource/clicky/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flanksource%2Fclicky/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34323994,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-27T10:18:29.742Z","updated_at":"2026-06-14T14:00:36.376Z","avatar_url":"https://github.com/flanksource.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Clicky\n\nClicky is a Go toolkit for turning structured data and Cobra CLIs into polished command-line, web, and AI-facing interfaces. It includes:\n\n- multi-format output for structs, maps, slices, and schema-driven data\n- styled terminal and HTML rendering based on `pretty` tags and Tailwind-like classes\n- concurrent task execution with progress rendering, retries, cancellation, and typed results\n- Echo middleware configured from Go or YAML\n- Cobra extensions for OpenAPI, Swagger UI, HTTP command execution, and MCP servers\n- helper packages for text processing, command execution, entity commands, and linting\n\nThe module path is:\n\n```bash\ngo get github.com/flanksource/clicky\n```\n\n## Install the CLI\n\n```bash\ngo install github.com/flanksource/clicky/cmd/clicky@latest\n```\n\nFor local development:\n\n```bash\nmake build\n./clicky --help\n```\n\nThe `clicky` binary formats JSON/YAML data with a schema, validates schemas, runs the API linter, and can expose its own Cobra commands through OpenAPI and MCP.\n\n```bash\nclicky pretty --schema examples/order-schema.yaml examples/example-data.json\nclicky pretty --schema examples/order-schema.yaml --format html --output order.html examples/example-data.json\nclicky schema validate examples/order-schema.yaml\nclicky schema example -o schema.yaml\nclicky lint ./...\n```\n\n## Library Usage\n\n### Format Structured Data\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\t\"github.com/flanksource/clicky\"\n)\n\ntype Server struct {\n\tName   string `pretty:\"label=Server\"`\n\tStatus string `pretty:\"color=green,sort\"`\n\tCPU    int    `pretty:\"label=CPU %,color=blue\"`\n}\n\nfunc main() {\n\tservers := []Server{\n\t\t{Name: \"api-01\", Status: \"ready\", CPU: 31},\n\t\t{Name: \"db-01\", Status: \"ready\", CPU: 54},\n\t}\n\n\tout, err := clicky.Format(servers, clicky.FormatOptions{Format: \"pretty\"})\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tfmt.Print(out)\n}\n```\n\nSupported formats include `pretty`, `json`, `yaml`, `csv`, `markdown`, `html`, `html-react`, `html-static`, `pdf`, `slack`, `excel`, and `tree`. Common aliases such as `md`, `yml`, and `xlsx` are accepted.\n\n`FormatOptions.Format` can also describe multiple sinks:\n\n```go\nclicky.PrintAndWriteSinks(data, clicky.FormatOptions{\n\tFormat: \"pretty,json=out.json,markdown=summary.md\",\n})\n```\n\n### Run Typed Tasks\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"time\"\n\n\t\"github.com/flanksource/clicky\"\n)\n\nfunc main() {\n\tjob := clicky.StartTask(\"load servers\", func(ctx clicky.Context, t *clicky.Task) ([]string, error) {\n\t\tfor i := 1; i \u003c= 3; i++ {\n\t\t\tt.SetProgress(i, 3)\n\t\t\ttime.Sleep(100 * time.Millisecond)\n\t\t}\n\t\treturn []string{\"api-01\", \"db-01\"}, nil\n\t})\n\n\tservers, err := job.GetResult()\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tfmt.Println(servers)\n\n\tclicky.WaitForGlobalCompletion()\n}\n```\n\nFor grouped work, use `clicky.StartGroup[T]` or `task.StartGroup[T]` with `task.WithConcurrency(n)`.\n\n### Add Common Flags to a Cobra CLI\n\n```go\nrootCmd := \u0026cobra.Command{Use: \"myapp\"}\nflags := clicky.BindAllFlagsToCommand(rootCmd, \"format\", \"tasks\")\n\nrootCmd.PersistentPreRun = func(cmd *cobra.Command, args []string) {\n\tflags.UseFlags()\n}\n```\n\nThis adds grouped logging, formatting, and task flags such as `--format`, `--filter`, `--no-color`, `--no-progress`, and `--max-concurrent`.\n\n### Add OpenAPI and MCP to a Cobra CLI\n\n```go\nimport \"github.com/flanksource/clicky/extensions\"\n\nextensions.CobraExtensions(rootCmd).All()\n```\n\nThis adds:\n\n- `openapi generate`\n- `openapi validate \u003cfile\u003e`\n- `openapi serve`\n- `mcp serve`\n- `mcp config`\n- `mcp tools`\n- `mcp install`\n- `mcp prompts`\n\nExample commands:\n\n```bash\nmyapp openapi generate --format yaml --output openapi.yaml\nmyapp openapi serve --port 8080 --enable-executor\nmyapp mcp tools --format markdown\nmyapp mcp serve --auto-expose\n```\n\n### Configure Echo Middleware\n\n```go\npackage main\n\nimport (\n\t\"log\"\n\n\t\"github.com/flanksource/clicky/middleware\"\n\t\"github.com/labstack/echo/v4\"\n)\n\nfunc main() {\n\te := echo.New()\n\n\tconfig, err := middleware.LoadConfigFromYAML(\"config/production.yaml\")\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tif err := middleware.ValidateConfig(config); err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tmiddleware.ApplyMiddleware(e, config)\n\tlog.Fatal(e.Start(\":8080\"))\n}\n```\n\nPreset helpers are also available:\n\n```go\nmiddleware.ApplyMinimalMiddleware(e)\nmiddleware.ApplyDefaultMiddleware(e)\nmiddleware.ApplyProductionMiddleware(e)\n```\n\n## Schema Formatting\n\nThe CLI can format dynamic JSON/YAML data using schema files. A schema describes fields, labels, types, styles, color rules, table fields, tree fields, and format-specific options.\n\n```yaml\nfields:\n  - name: id\n    label: Order ID\n    type: string\n    style: text-blue-600 font-bold\n  - name: status\n    type: string\n    color_options:\n      green: completed\n      yellow: processing\n      red: failed\n  - name: total_amount\n    type: float\n    format: currency\n  - name: items\n    type: array\n    format: table\n    table_options:\n      fields:\n        - name: product_name\n          type: string\n        - name: quantity\n          type: int\n        - name: price\n          type: float\n          format: currency\n```\n\nGenerate a fuller example with:\n\n```bash\nclicky schema example\n```\n\n## Package Map\n\n- `api`: render primitives such as text, tables, trees, code blocks, badges, links, stack traces, and schema parsing\n- `formatters`: output managers and implementations for terminal, JSON, YAML, CSV, Markdown, HTML, PDF, Excel, Slack, and tree formats\n- `task`: task manager, typed tasks, groups, progress rendering, retries, shutdown handling, and output capture\n- `middleware`: Echo v4 middleware configuration, validation, auth, interceptors, and presets\n- `rpc`: Cobra-to-OpenAPI generation, Swagger UI server, validation, and HTTP command execution\n- `mcp`: Model Context Protocol server and tool discovery for Cobra commands\n- `extensions`: fluent helpers that attach OpenAPI and MCP commands to Cobra roots\n- `exec`: command execution wrappers with logging and process-group handling\n- `flags`: struct-tag flag binding helpers\n- `text`: tokenization, redaction, and line processing utilities\n- `lint`: Go analyzer for Clicky API usage\n\n## Development\n\n```bash\ngo mod download\nmake test\nmake lint\nmake build\n```\n\nUseful targeted commands:\n\n```bash\ngo test ./formatters/...\ngo test ./task/...\ngo test ./middleware/...\ngo test -tags integration ./rpc/... -run TestOpenAPIServe_E2E\n```\n\nThe task UI bundle is built separately:\n\n```bash\nmake task-ui\n```\n\n## Examples\n\nThe `examples/` directory includes focused demos for:\n\n- schema-driven formatting\n- Cobra integration\n- OpenAPI and Swagger serving\n- MCP integration\n- Echo middleware\n- task manager behavior\n- file tree, PDF widgets, and entity workflows\n\nStart with `examples/README.md` and the schema/data pairs in `examples/order-schema.yaml` and `examples/example-data.json`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflanksource%2Fclicky","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflanksource%2Fclicky","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflanksource%2Fclicky/lists"}