dotslash-files

This repository stores DotSlash wrapper files used across projects. A DotSlash file (commonly given a .dotslash extension) is a small script-like file that must begin with the shebang:

#!/usr/bin/env dotslash

and contain a JSON body that tells the dotslash runtime how to fetch and run the executable it represents. Any arguments passed on the dotslash command line after the DotSlash file are forwarded to the underlying executable.

Quick usage

• Run a DotSlash file:

dotslash ./tool.dotslash -- <args>

• Validate / inspect a DotSlash file:

dotslash -- parse ./tool.dotslash

• Prepare (fetch) the executable without running it:

dotslash -- fetch ./tool.dotslash

• Compute checksums:

dotslash -- sha256 FILE
dotslash -- b3sum FILE

Example DotSlash file (illustrative)

#!/usr/bin/env dotslash

{
  "name": "mytool",
  "provider": { "http": "https://example.com/bin/mytool-<platform>.tar.gz" },
  "run": { "cmd": ["mytool"] }
}

Testing & validation

• Make the file executable:

chmod +x ./tool.dotslash

• Validate JSON syntax (optional):

jq . ./tool.dotslash

• Use dotslash -- parse and dotslash -- fetch to verify behaviour on your host.

Best practices

• Use the #!/usr/bin/env dotslash shebang and prefer a .dotslash extension for clarity.
• Avoid hardcoding platform-specific paths; use provider templates and runtime outputs instead (see --help for supported placeholders).
• Pin artifacts with checksums when possible and prefer stable, versioned downloads.
• For deployment, you can rename a .dotslash file to the target binary name and place it in a directory on your PATH (for example, node-v24.0.0.dotslash -> ~/bin/node). After moving the file, ensure it is executable (for example: chmod +x ~/bin/node).

Repository organization

Store DotSlash files in a logical location (root, a tools/ directory, or a dedicated dots/ directory). Keep files small, well-documented, and executable.

Included scripts

• scripts/dotslash-sandbox

  • Run a .dotslash file in a Podman container for hermetic, reproducible execution.
    • Usage: ./scripts/dotslash-sandbox <file.dotslash> [args...]

• scripts/dotslash-shim

  • Lightweight shim that ensures a pinned dotslash binary is available in $HOME/.cache/dotslash-shim/bin/dotslash; downloads and verifies v0.5.8 if missing.
  • Usage: Invoke directly (./scripts/dotslash-shim) or let dotslash-sandbox mount it into containers.
  • Use cases: Run dotslash on systems without a global install (CI, containers), provide an isolated, verifiable runtime for DotSlash files.

• scripts/dotslash-doctor

  • Update .dotslash assets by downloading and verifying remote files.
  • Usage: ./scripts/dotslash-doctor <file.dotslash>
  • Use cases: Verify and update size, sha256, and path for platforms in a .dotslash file.

• scripts/dotslash-install

  • Install a .dotslash manifest from this repository's bin/ into a local bin directory and create a small wrapper that runs dotslash <manifest>.
  • Usage: ./scripts/dotslash-install [OPTIONS]
  • Example: ./scripts/dotslash-install fzf (installs the 'fzf' manifest and creates a wrapper in the target directory).
  • See docs/dotslash-install-plan.md for implementation details and testing notes. Run make install-tests to execute the install test suite locally.

References

• Official project: dotslash-cli.com

Contributing

1. Add your DotSlash file (make it executable).
2. Validate locally with dotslash -- parse and dotslash -- fetch.
3. Open a PR describing the tool, platforms supported (if any), and any checksums or verification steps.