If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/TomWright/dasel shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 3d ago
• 7 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 88% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live TomWright/dasel repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/TomWright/dasel.

What it runs against: a local clone of TomWright/dasel — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in TomWright/dasel | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of TomWright/dasel. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/TomWright/dasel.git
#   cd dasel
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of TomWright/dasel and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "TomWright/dasel(\\.git)?\\b" \\
  && ok "origin remote is TomWright/dasel" \\
  || miss "origin remote is not TomWright/dasel (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "cmd/dasel/main.go" \\
  && ok "cmd/dasel/main.go" \\
  || miss "missing critical file: cmd/dasel/main.go"
test -f "api.go" \\
  && ok "api.go" \\
  || miss "missing critical file: api.go"
test -f "execution/execute.go" \\
  && ok "execution/execute.go" \\
  || miss "missing critical file: execution/execute.go"
test -f "execution/func.go" \\
  && ok "execution/func.go" \\
  || miss "missing critical file: execution/func.go"
test -f ".github/workflows/test.yaml" \\
  && ok ".github/workflows/test.yaml" \\
  || miss "missing critical file: .github/workflows/test.yaml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/TomWright/dasel"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Dasel is a CLI tool and Go library that provides a unified query and modification syntax for traversing and transforming structured data across 7 different formats (JSON, YAML, TOML, XML, CSV, HCL, INI). It solves the problem of format-switching friction by letting users query, modify, and convert between these formats using identical selector syntax without writing format-specific parsers. Modular monorepo structure: cmd/dasel/main.go is the CLI entry point, api.go/api_test.go expose the library API, and execution/ package contains 40+ files implementing selector operations (execute_array.go, execute_filter.go, execute_assign.go, etc.) with corresponding _test.go files. .github/workflows orchestrates CI across build, test, CodeQL, and container publishing.

DevOps engineers, SREs, and data engineers who need to extract/modify values in config files (Kubernetes YAML, Terraform HCL, CI/CD JSON artifacts) within shell scripts and pipelines; Go developers embedding structured data querying into applications; CI/CD pipeline maintainers who need to transform configs across multiple formats without separate jq/yq/toml-cli tools.

Production-ready with active maintenance: 569KB+ of Go code, comprehensive GitHub Actions CI (test, build, CodeQL, golangci-lint), codecov integration, and recent go.mod updates to 1.25. High visibility (Awesome Go mention, 50+ Homebrew installs daily badge). Code appears stable with dedicated execution/ package test suites for each operation type.

Low risk overall: single-maintainer project (TomWright) which is typical for popular CLI tools, but recent go mod updates suggest active development. Dependency count is moderate (~20 direct) with well-maintained upstream (alecthomas/kong for CLI parsing, charmbracelet for TUI, hashicorp/hcl for HCL support). No obvious breaking changes visible in CHANGELOG pattern.

Active development with recent Go 1.25 compatibility, bumped dependencies (charmbracelet, pelletier/go-toml), and maintained Homebrew formula automation (bump-homebrew.yaml workflow). CodeQL security scanning enabled. Presence of container.yaml suggests OCI image publishing alongside binary releases.

git clone https://github.com/TomWright/dasel.git && cd dasel && go install ./cmd/dasel@latest OR go install github.com/tomwright/dasel/v3/cmd/dasel@master OR brew install dasel (macOS/Linux)

Daily commands: go test ./... for unit tests (see .github/workflows/test.yaml), dasel --help to verify installation, dasel select '.foo.bar' -f json input.json to query data

• cmd/dasel/main.go — Entry point for the CLI application; all contributors must understand command-line argument parsing and initialization flow.
• api.go — Core public API for programmatic dasel usage; essential for understanding how to select, put, and delete data across all formats.
• execution/execute.go — Central query execution engine that orchestrates all expression evaluation; fundamental to understanding how dasel processes queries.
• execution/func.go — Function registry and dispatcher for all built-in functions; required reading for adding new operations or understanding function resolution.
• .github/workflows/test.yaml — Test automation pipeline; defines coverage expectations and testing standards that all PRs must satisfy.
• go.mod — Dependency manifest showing critical format parsers (YAML, TOML, HCL, YAML) and CLI framework (kong); essential for understanding external contracts.

• CLI (cmd/dasel/main.go) (Kong, io/fs) — Parse command-line arguments, load file from disk, invoke API, format and print results, exit with appropriate status code.
  • Failure mode: Invalid flags, missing files, malformed paths → exit with helpful error message
• API (api.go) (External format parsers) — Public-facing Select, Put, Delete methods; detect file format, parse input, delegate to execution engine, serialize output.
  • Failure mode: Unknown format → attempt to detect or error; unsupported operation → return detailed error
• Execution Engine (execution/execute.go) (Go reflection, recursive evaluation) — Interpret and evaluate dasel query language; route to specialized operators and functions; aggregate results.
  • Failure mode: Type mismatch (e.g., array access on string) → nil or error; invalid query syntax → parser error
• Function Library (execution/func.go)* (Go standard library) — Implement domain-specific operations: string/array/object manipulation, arithmetic, aggregation, type coercion.
  • Failure mode: Incompatible types → function returns error; division by zero → trapped and reported
• Format Parsers (via go.mod dependencies) (go-toml, go.yaml, hashicorp/hcl, gopkg.in/ini, encoding/json, encoding/csv) — Convert raw file bytes into Go interface{} representation; unmarshal and remarshal as needed.
  • Failure mode: Malformed input → parser error with line/column info; unsupported syntax → parse error

• `` → undefined — undefined

Add a new built-in function

1. Create a new executor file following the pattern func_FUNCTIONNAME.go in execution/ (execution/func_example.go)
2. Implement the function signature matching execution.FuncHandler type with input validation and error handling (execution/func.go)
3. Register the function in the funcs map within func.go with a lowercase name matching CLI usage (execution/func.go)
4. Add comprehensive unit tests in func_FUNCTIONNAME_test.go covering success, error, and edge cases (execution/func_example_test.go)

Add a new query operator (e.g., new selector syntax)

1. Create execute_OPERATORNAME.go in execution/ with logic to process the operator (execution/execute_custom.go)
2. Update the main execute.go dispatcher to recognize and route to your new operator handler (execution/execute.go)
3. Create thorough tests in execute_OPERATORNAME_test.go with various input scenarios (execution/execute_custom_test.go)
4. Document the operator in the README.md with examples and syntax (README.md)

Add support for a new file format

1. Add the format parser library to go.mod (e.g., go get github.com/parser/library) (go.mod)
2. Extend the format detection and parsing logic in api.go to recognize and parse the new format (api.go)
3. Add API tests in api_test.go with sample files in the new format (api_test.go)
4. Update CLI help and README with the new format support (README.md)

• Go 1.25 — Fast compilation, static typing, small binary footprint, and excellent cross-platform support for CLI tooling.
• Kong CLI framework — Declarative command-line argument parsing reduces boilerplate and ensures consistent flag handling.
• External format parsers (go-toml, go.yaml, hashicorp/hcl, gopkg.in/ini) — Delegating parsing to specialized libraries ensures correctness and maintainability for complex formats.
• Bubbletea/Bubbles TUI — Interactive mode support for exploring and modifying data with rich terminal UI.
• go-cmp for testing — Deep structural comparison in tests avoids brittle string assertions and catches subtle bugs.

• Single-pass query execution (no pre-optimization phase)

  • Why: Simplifies implementation and keeps execution predictable for users.
  • Consequence: Complex queries may not be as performant as a multi-pass optimized engine, but typical usage remains sub-millisecond.

• Support multiple file formats simultaneously in one tool

  • Why: Provides unifying interface for data manipulation across heterogeneous infrastructure.
  • Consequence: Larger binary, complex format-detection logic, and testing burden across all format combinations.

• Immutable query execution (select/put creates new structure, doesn't mutate input)

  • Why: Prevents side effects and makes behavior predictable.
  • Consequence: Higher memory usage for large data structures; streaming mode not fully supported.

• Real-time data streaming or incremental parsing (designed for discrete file operations)
• GraphQL or SQL query language support (dasel is its own domain-specific language)
• Two-way JSON schema validation (validates structure during access, not schema-first)
• Distributed or multi-file aggregation queries (single-file scope only)
• Custom script/plugin execution within queries (functions are built-in only)

No major gotchas in typical use, but: (1) Selector syntax is custom (not jq-compatible), learn it via daseldocs.tomwright.me docs; (2) CSV support is more limited than JSON/YAML due to format constraints; (3) HCL parsing uses HashiCorp's engine which requires proper HCL2 syntax; (4) Interactive mode (TUI from charmbracelet deps) only works in certain contexts, not in piped stdin.

• Selector/Path expression — Dasel's core abstraction: a domain-specific language for querying nested structures across different formats. Understanding how selectors map to tree paths is essential to using and extending the tool.
• Visitor pattern (tree traversal) — The execution/ package uses visitor-like pattern to walk data structures; understanding how Execute() recursively traverses nodes explains how selectors are evaluated.
• Format abstraction layer — Dasel normalizes 7 different parsing libraries (go-yaml, go-toml, hashicorp/hcl, encoding/xml) into a unified tree model; this abstraction is why multi-format querying works seamlessly.
• Abstract syntax tree (AST) parsing — Selector syntax is parsed into an AST before execution; understanding how Kong CLI parser and selector tokenization work is key to extending selector syntax.
• In-place mutation patterns — The execute_assign.go and delete operations must modify data structures in-place while preserving format fidelity; Go's reflection and pointer semantics are crucial here.
• Format normalization — Each format (XML attributes vs object keys, YAML anchors, CSV headers) has quirks; dasel's success depends on mapping these to a canonical internal representation without data loss.

• mikefarah/yq — YAML-specific query tool with similar goal but YAML-only; comparison point for why dasel's multi-format approach is valuable
• stedolan/jq — Canonical JSON query language that inspired many alternatives; users familiar with jq syntax often compare to dasel
• hashicorp/hcl — Upstream HCL parser that dasel depends on (hashicorp/hcl/v2); understanding HCL semantics helps with dasel's HCL support
• pelletier/go-toml — TOML parser library that dasel uses as a direct dependency for TOML format support
• compose-spec/compose-go — Uses similar multi-format config handling pattern in Go; relevant for understanding data structure abstraction layers

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive tests for execute_ternary.go

The file execute_ternary_test.go is missing from the execution directory despite execute_ternary.go existing. Ternary operators are critical control flow operations that deserve thorough test coverage. This gap could allow regressions in conditional expression handling across all supported formats (JSON, YAML, TOML, XML, etc.).

• [ ] Create execution/execute_ternary_test.go with test cases for basic ternary operations
• [ ] Add edge cases: null/undefined conditions, various return types, nested ternaries
• [ ] Test ternary operations across different data format parsers (JSON, YAML, TOML, XML)
• [ ] Ensure coverage matches other similar test files (execute_conditional_test.go pattern)
• [ ] Run codecov to verify coverage improvement

Add missing unit tests for execute_search.go

The file execute_search.go exists but has no corresponding execute_search_test.go file. Search functionality is a core feature of dasel for querying data structures. Without dedicated tests, search behavior across different data types and nested structures may not be properly validated.

• [ ] Create execution/execute_search_test.go following existing test patterns
• [ ] Add test cases for basic search, nested object search, and array element search
• [ ] Test search with special characters and escape sequences
• [ ] Test search behavior with different data types (strings, numbers, booleans)
• [ ] Include tests for case sensitivity and partial matching behavior

Create GitHub Actions workflow for pre-commit hook validation

The repo has .pre-commit-hooks.yaml configured but no dedicated CI workflow to validate that hooks work correctly across different environments. This ensures contributors and users get consistent formatting/linting regardless of local setup. Currently golangci-lint.yaml and test.yaml exist, but pre-commit hooks aren't validated as part of CI.

• [ ] Create .github/workflows/pre-commit-validate.yaml workflow file
• [ ] Add steps to install pre-commit framework and run against staged files
• [ ] Configure matrix for multiple Go versions matching go.mod (1.25+)
• [ ] Validate that hook definitions in .pre-commit-hooks.yaml are syntactically correct
• [ ] Add workflow trigger for PRs and pushes to main/master branch

1. Add missing tests in execution/ package: several execute_.go files are present but some may lack edge case coverage (check which ones have <80% coverage in codecov report). 2. Extend CSV selector documentation and examples: README mentions CSV support but actual selector syntax examples for CSV are sparse—add documentation in docs/ or CONTRIBUTING.md with concrete examples. 3. Performance benchmarking suite: Add go bench files (execution/_bench.go) to measure selector evaluation speed on large files, helping identify bottlenecks.

The codebase demonstrates good security hygiene with proper disclosure policies, containerization, and dependency management practices. However, there are concerns regarding the use of unreleased/pre-release versions of Go and key dependencies (YAML, TOML libraries), which may lack stability and security patches. The Dockerfile and base image configuration could be strengthened with more specific versioning and digest pinning. The SECURITY.md policy should be completed. Overall, these are manageable issues that should be addressed to improve stability and security posture.

• Medium · Unreleased/Pre-release Go Version in Dockerfile — Dockerfile (line 1: ARG GOLANG_VERSION=1.25.0). The Dockerfile uses Go 1.25.0, which appears to be a future/unreleased version. This may indicate the use of development builds or unstable versions that lack security patches and stability guarantees. Go modules should use stable, officially released versions. Fix: Use a stable, officially released Go version (e.g., 1.23.x or the latest stable 1.24.x release). Verify that the version is available on golang.org before deployment.
• Medium · YAML Library Using Pre-release Version — go.mod (line: go.yaml.in/yaml/v4 v4.0.0-rc.3). The go.mod file specifies 'go.yaml.in/yaml/v4 v4.0.0-rc.3', which is a release candidate (pre-release). Release candidates are not considered stable and may contain unresolved bugs or security issues. Fix: Upgrade to the stable release version of the YAML library once available, or use a known stable version (v3). Track upstream releases and migrate when stability is reached.
• Low · TOML Library Using Pre-release Version — go.mod (line: github.com/pelletier/go-toml/v2 v2.2.5-0.20250826075308-a0e846496753). The go.mod file specifies 'github.com/pelletier/go-toml/v2 v2.2.5-0.20250826075308-a0e846496753', which is a pseudo-version from an unreleased commit. This may indicate an unstable or development version. Fix: Pin to a stable released version of go-toml/v2 (e.g., v2.2.0 or later stable release). Use 'go get -u' to fetch the latest stable version.
• Low · Missing Security Policy Completion — SECURITY.md (end of file). The SECURITY.md file appears to be incomplete. The section 'If the report is declined,' ends abruptly without finishing the statement, which may confuse reporters about the expected response. Fix: Complete the SECURITY.md policy documentation to clearly explain all expected outcomes, including what happens if a report is declined. This improves transparency and trust.
• Low · Docker Base Image Should Be Pinned — Dockerfile (line 6: ARG TARGET_BASE_IMAGE=debian:bookworm-slim). The Dockerfile uses 'ARG TARGET_BASE_IMAGE=debian:bookworm-slim' without a specific digest. While using slim variants is good practice, base images should be pinned by digest to ensure reproducible builds and prevent unexpected image changes. Fix: Pin the base image to a specific digest: 'debian:bookworm-slim@sha256:...' to ensure consistent and reproducible builds across environments.
• Low · Dependency Management Lacks Lock File Verification — .github/workflows/. While go.mod and go.sum provide dependency management, there is no evidence of automated dependency scanning or verification in the CI/CD pipeline based on the provided workflow files. Fix: Implement automated dependency scanning using 'go mod tidy', 'go mod verify', or tools like Dependabot and OWASP Dependency-Check in CI/CD pipelines to detect known vulnerabilities.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.