vaultools

CLI for the Vaultools dev micro-tools — JSON formatting, JWT and X.509 certificate decoding, Base64, URL and HTML entity encoding, cron and Unix permission explanations, UUID/hash generation, regex testing, timestamp conversion, and identifying what an unknown string is — for CI pipelines and scripting, where a browser tool or editor extension can't run headlessly.

The only network call this CLI ever makes is Pro license verification. Every actual tool operation (formatting JSON, decoding a JWT or certificate, hashing text, explaining a cron schedule, and so on) runs entirely on your machine, using the exact same pure, unit-tested logic as vaultools.dev's browser tools — nothing you pipe through this CLI is ever sent anywhere.

Install

npm install -g vaultools

Or run it without installing:

npx vaultools json format package.json

Requires Node.js ≥20.

Usage

Every command accepts input either as a positional argument/file path, or via stdin if omitted — so it composes naturally in a pipeline:

echo '{"a":1}' | vaultools json format
vaultools json format package.json
cat token.txt | vaultools jwt decode

Text transforms (url, entity) drop one trailing newline from stdin, so echo 'a b' | vaultools url encode gives a%20b. base64 encode keeps it, like base64(1); use printf to avoid encoding it. Quote cron expressions, since the shell expands *, and put -- before an argument that starts with a dash: vaultools chmod apply 666 -- -w.

Pass --json (before the subcommand) for machine-readable output that mirrors the underlying result shape 1:1, so it's directly jq-able:

vaultools --json json format package.json | jq '.formatted'

Commands

| Command | Free/Pro | Description | |---|---|---| | json format [file] | Free | Pretty-print/validate JSON (--indent <n>) | | json to-ts [file] | Free | Infer a TypeScript interface from sample JSON (--root-name <name>) | | json batch [file] | Pro | Format many ----delimited JSON documents at once | | regex test <pattern> [file] | Free | List all matches (--flags <flags>) | | regex replace <pattern> <replacement> [file] | Free | Replace matches (--flags <flags>) | | regex batch <pattern> [file] | Pro | Match+replace against many lines at once (--flags, --replacement) | | hash text [value] | Free | Hash text with one algorithm (--algorithm SHA-1\|SHA-256\|SHA-384\|SHA-512) | | hash all [value] | Free | Hash text with every supported algorithm | | hash lines [file] | Pro | Hash each non-blank line independently (--algorithm) | | uuid | Free | Generate a single v4 UUID | | uuid batch --count <n> | Pro | Generate many v4 UUIDs at once (1-500) | | jwt decode [token] | Free | Decode a JWT's header/payload (no signature verification) | | timestamp to-date [value] | Free | Convert a Unix timestamp to ISO/UTC/local/relative | | timestamp to-unix [value] | Free | Convert a date string to epoch seconds/ms | | timestamp batch [file] | Pro | Convert many newline-separated timestamps at once | | x509 decode [file] | Free | Decode a PEM certificate or whole chain: subject, issuer, validity, names, key, fingerprints | | x509 expiry [files...] | Pro | Check every certificate in one or more files; fails if any expire within --within (default 30d) | | base64 encode [value] | Free | Encode text, or a file's bytes with --file <path> (--url-safe, --no-padding) | | base64 decode [value] | Free | Decode Base64 or Base64URL; --out <path> saves binary data | | url encode [value] | Free | Percent-encode (--style component\|uri\|form) | | url decode [value] | Free | Decode percent-encoding (--plus-as-space) | | url parse [value] | Free | Break a URL or query string into parts and decoded parameters | | cron explain <expression> | Free | Explain a five-field schedule and list its next runs (--next <n>, --utc) | | cron lint [file] | Pro | Check every schedule in a crontab; fails on any invalid line (--expressions for bare lists) | | chmod explain <mode> | Free | Explain 755 or -rwxr-xr-x for a file or --dir | | chmod apply <mode> <change> | Free | Show what u+x, go-w or 640 would do, following GNU chmod (--dir, --umask) | | chmod umask <mask> | Free | Show the modes new files and directories get | | chmod audit [file] | Pro | Flag world-writable, setuid and other risky modes in stat/find output; fails on any finding | | entity encode [value] | Free | Escape & < > " ' for HTML (--all for non-ASCII too, --format named\|decimal\|hex) | | entity decode [value] | Free | Decode entities as a browser would, warning about likely mistakes | | entity lookup <query> | Free | Find entities by name, character or code point (--limit <n>) | | identify [value] | Free | Say what a string is (JWT, JSON, certificate, Base64, cron, timestamp, ...) and which command opens it; fails if nothing matches |

chmod never changes a file: it only explains and calculates.

identify recognizes 13 formats, each by a simple rule (the same ones the Format Identifier lists). When more than one matches, the most specific comes first. It never claims to recognize encrypted data, since that is indistinguishable from random bytes:

$ vaultools identify eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjQxMDI0NDQ4MDB9.x
JWT
  Three Base64URL parts, signed with HS256, expires 1 Jan 2100
  Open it with: vaultools jwt decode

$ cat cert.pem | vaultools --json identify | jq -r '.matches[0].format'
x509

Run vaultools <command> --help for full option details on any command.

Pro features

Single-value operations are free and unlimited. Batch/multi-value operations — the ones that matter most for CI (validating a directory of JSON files, hashing every line of a manifest, etc.) — require a Pro license, the same one used on vaultools.dev/pro:

vaultools login <your-license-key>
vaultools license status
vaultools logout

The license is cached locally at $XDG_CONFIG_HOME/vaultools/license.json (falls back to ~/.config/vaultools/license.json) and re-verified against the server roughly once a week — no license check runs on every invocation.

CI example

# GitHub Actions: fail the job if any generated config isn't valid JSON
- name: Validate JSON configs
  run: npx vaultools json format config/generated.json

With a Pro license (vaultools login in a setup step, key from a secret), the check commands fail the job on any problem:

- name: Certificates valid for at least 30 more days
  run: npx vaultools x509 expiry certs/*.pem --within 30d

- name: Crontab schedules are valid
  run: npx vaultools cron lint deploy/crontab

- name: No world-writable or setuid files in the image
  run: docker run --rm my-image find /app -printf '%M %p\n' | npx vaultools chmod audit

Links

• vaultools.dev
• vaultools.dev/pro — get a license key
• Issues/feedback: vaultools.dev/contact

The two recordings above are the real CLI, scripted and not staged — same idea as the browser tool demos on vaultools.dev.