JSON output

JSON-by-default output on stdout, a stable error envelope on stderr, and meaningful exit codes for scripting.

Every command emits one JSON line on success. Errors go to stderr with a stable { error: { code, message } } envelope, never mixed with the success channel — so a JSON parser downstream sees either a clean record or nothing.

# JSON output is the default — pipe straight to jq.
$ files --provider fs --root /tmp/store head reports/q1.pdf
{"key":"reports/q1.pdf","name":"q1.pdf","size":48213,"type":"application/pdf","lastModified":1778881504647,"etag":"\"9feb94ca37e5d155\""}

# Errors go to stderr with a stable error code. Exit codes:
#   0  ok
#   1  NotFound (or exists → false)
#   2  Provider / unknown error
#   3  Unauthorized
#   4  Conflict
$ files --provider fs --root /tmp/store head nope.txt
{"error":{"code":"NotFound","message":"ENOENT: no such file or directory, stat '/tmp/store/nope.txt'"}}
$ echo $?
1

Use --pretty for indented JSON when reading manually, or --no-json for plain-text output (still suitable for grep, just not for parsing).