For Agents

If you're driving files-cli from an AI agent — or building an agent that uses it — start with these:

Resource	Description
CONTEXT.md	CLI-wide invocation contract: authentication, global flags, output format, error conventions.
skills/	`SKILL.md` packages — one per top-level CLI command (Bundles, Users, Files, …), grouped by category.
skills/INDEX.md	Full index of skills.
agents/tool-catalog.json	Machine-readable catalog of the API resource commands and their parameters, generated from the API schema.
agents/error-catalog.json	Machine-readable catalog of known error types with HTTP codes.

Core invocation:

files-cli <domain> <subcommand> --format json --non-interactive [flags...]

Pass --format json so output is structured (the default table is for humans).
Pass --non-interactive so the CLI never blocks on a prompt.
Exit code 0 is success. Non-zero is failure; read diagnostics from stderr. --format json does not provide a uniform JSON error envelope.

For Claude Code, Codex, or any agent that supports filesystem-loaded skills, point the skills directory at skills/. For agents without skill loading, load the relevant SKILL.md directly into context based on the task at hand.

The installed binary can also describe itself, offline and without credentials, matched to its version:

files-cli commands                               # top-level commands and groups
files-cli commands search share link             # find commands by keyword
files-cli commands describe folders list-for --format json
files-cli workflows show recipe-searching-for-files
files-cli workflows show filescom-permissions

commands describe also reports a hint about the command's effect (read_only, mutating, or destructive; guidance, not an enforced guarantee), the fields of the records it prints for use with --fields, and links to the guides for the command. See CONTEXT.md for details.

To read a long list a page at a time, add --json-envelope to a list command. It prints {"has_more", "next_cursor", "data"} for one page; pass next_cursor back with --cursor to continue. Without the flag, --format json output is unchanged. See CONTEXT.md for details.