fs CLI

fs is the human- and agent-friendly command-line client for the file hosting service. It requires Node.js 22 or newer.

Install

Install globally from npm:

npm install --global @moulikbudhiraja/fs-cli

Or link a development checkout:

npm install
npm run build
npm link

Save the shared bearer token in the operating system credential store (macOS Keychain, Windows Credential Manager, or the Linux secret service):

fs auth set
fs auth status

The prompt does not echo the token. To remove the saved token, run fs auth delete. The noninteractive auth status and auth delete actions accept and ignore the global --no-input flag. auth set always requires an interactive terminal and rejects --no-input; use FS_TOKEN instead in noninteractive environments.

For CI and other noninteractive environments, configure the endpoint and token with environment variables instead:

export FS_URL=https://files.moulik.dev  # this is the default
export FS_TOKEN=replace-with-the-shared-secret

FS_TOKEN takes precedence over a saved credential when both are present. Saved credentials are scoped to FS_URL, so different servers do not share tokens. Linux desktop environments normally provide Secret Service; headless Linux sessions need an unlocked compatible keyring on the session D-Bus or should use FS_TOKEN.

Commands

Upload is the default action; up is its explicit spelling:

fs report.pdf --tag report
fs up report.pdf screenshot.png --private
fs up '**/*.json' --tag data
fs -r ./results
some-command | fs up - --name output.log

Quoted globs support *, **, and ?. Shell-expanded arguments work too, duplicate matches are uploaded once, and hidden files are matched only by a pattern that explicitly includes their leading dot. A directory is rejected unless -r/--recursive is present; each directory is then stored as one .tar.gz object without following symlinks.

An invocation whose combined logical input size is over 1 GiB needs interactive human confirmation or an explicit --allow-large-upload after approval. In noninteractive mode it exits with status 7 instead of prompting. --no-input forces noninteractive behavior.

fs down Ab12xY9
fs down Ab12xY9 -o report.pdf
fs down Ab12xY9 -o - | sha256sum
fs down Ab12xY9 --extract -o ./results

fs list
fs find quarterly --name '*.pdf' --tag finance
fs info Ab12xY9
fs tag Ab12xY9 add reviewed important
fs visibility Ab12xY9 protected
fs visibility Ab12xY9 private
fs rm Ab12xY9 --yes

Downloads do not overwrite existing paths unless --force is supplied. --extract is accepted only for objects recorded as CLI-created tar.gz archives, and extraction rejects traversal paths and unsafe links.

Scripting

Requested data is written to stdout. Warnings and diagnostics go to stderr. Collection commands support JSON arrays, streaming JSON Lines, or ID-only output:

fs list --json
fs find --tag temporary --jsonl
fs find --tag temporary --ids
fs find --tag temporary --ids --null |
  while IFS= read -r -d '' id; do
    fs --no-input rm "$id" --yes
  done

id="$(fs report.pdf --id)"
fs info "$id" --json

The CLI never prompts when standard streams are redirected or when --no-input is set. Uploads and file downloads that are still running after 2.5 seconds show live bytes, rate, and (when the size is known) percentage and ETA on an interactive stderr. Fast transfers, machine-readable upload modes, redirected stderr, and downloads streamed with -o - do not show progress. Progress never writes to stdout. Output contains no color control sequences.

Stable exit statuses are:

| Status | Meaning | |---:|---| | 0 | success | | 1 | general failure | | 2 | invalid arguments or unmatched glob | | 3 | authentication failure | | 4 | not found | | 5 | conflict, such as an existing output path | | 6 | network or server failure | | 7 | human approval required | | 8 | partial success |

Releasing to npm

The release workflow publishes only from stable cli-vX.Y.Z tags whose version exactly matches cli/package.json and whose commit is on main. Before the first release, add a GitHub Actions Trusted Publisher at https://www.npmjs.com/package/@moulikbudhiraja/fs-cli/access with:

• Organization or user: Moulik-Budhiraja
• Repository: File-Hosting
• Workflow filename: publish-cli.yml
• Environment name: leave blank
• Allowed actions: npm publish only

Keep the maintainer account's 2FA enabled; the workflow uses GitHub OIDC and has no npm token. After a release change is merged, run the checks below from cli/, explicitly authorize that version for publication, then create and push the matching tag. Never push a release tag merely to test the workflow.

npm ci
npm audit --omit=dev
npm run typecheck
npm test
npm run build
npm pack --dry-run
git tag cli-vX.Y.Z <main-commit>
git push origin cli-vX.Y.Z

Development checks

npm run typecheck
npm test
npm run build