CLI Reference

This page is the reference behind filestarcli agent readme. The readme that comes with your CLI always matches its version; when the two differ, follow the readme.

The loop

filestarcli detect <files> --json: what kind of file is it?
filestarcli skills -i <file> --json: what can Filestar do with it?
filestarcli skills describe "<command>" -i <file> --json: which parameters does the command take?
filestarcli -i <file> -c "<command>" --json --user-agent <agent>: run it, then read outputs.

Commands

Command	What it does
`filestarcli -i <files> -c "<command>"`	Runs a command, such as `"convert to jpg"` or `"resize to 50% and convert to webp"`, on the files.
`filestarcli -i <files> --recipe <file>`	Runs a stored recipe.
`filestarcli detect <files>`	Identifies files from their contents. No account and no network needed.
`filestarcli skills -i <files>`	Lists the commands available for the files.
`filestarcli skills describe "<command>" -i <files>`	Lists a command's parameters, defaults and allowed values.
`filestarcli doctor`	Checks that this computer is ready to run skills (`readiness` still works).
`filestarcli account`	The plan on this computer, the free runs left and an upgrade link.
`filestarcli upgrade [--wait] [--open]`	Prints a link to choose a plan for this computer. `--wait` waits until it is paid; `--open` also opens it in the browser.
`filestarcli login <email> [--wait]`	Emails a sign-in link for an existing Filestar account. `--wait` waits until the link is used.
`filestarcli register <licence key>`	Registers this computer with a licence key.
`filestarcli unregister`	Removes this computer's registration.
`filestarcli update`	Updates the CLI. A conversion never updates or installs anything by itself.
`filestarcli version`	Prints the version.
`filestarcli agent readme [--format json]`	The guide for agents, as markdown or JSON.
`filestarcli agent install [--agent <id>…] [--kind skill\|mcp\|both] [--yes] [--json]`	Adds Filestar to agents on this computer.
`filestarcli agent list`	Shows which agents Filestar is added to.
`filestarcli agent uninstall`	Removes Filestar from agents again.
`filestarcli mcp`	Runs the MCP server on stdio.

Agent ids for --agent: claude-code, codex, claude-desktop, cursor, vs-code, gemini-cli, copilot-cli, opencode, windsurf.

Options for a run

Option	What it does
`-i`, `--input`	Files, folders or wildcards (`*.heic`).
`-c`, `--command`	The command, in plain words.
`-p Name:value`	A parameter, as listed by `skills describe`. Repeat it for more.
`--parameters-json '{"Width":800}'`	All parameters as one JSON object. Checked before anything runs.
`--output-dir <folder>`	Where to write the results. Default: next to each input.
`--overwrite`	Replace existing files. By default nothing is overwritten.
`-r`, `--recursive`	Include subfolders.
`--cloud Disallowed\|Allowed\|Forced`	Whether cloud skills may run. Pass `Disallowed` when files must stay on the computer; never pass `Forced` unless the person asked.
`--dry-run`	Shows which skills would run, with which parameters, and whether locally or in the cloud. Costs nothing.
`--json`	One JSON document on stdout.
`--progress json`	Progress as one JSON object per line on stderr.
`--user-agent <name/version>`	Who is running the CLI, for example `claude-code/2.1`. Or set `FILESTAR_USER_AGENT`.
`--timeout <seconds>`	Stop after this long, with exit code 7.

The options from Filestar CLI, such as -o and --recipe, work as before.

When stdout is not a terminal, the CLI writes no colour, progress bars or spinners, and it honours NO_COLOR. Errors always go to stderr, also with --loglevel Quiet.

The JSON result

With --json, every command writes one JSON document to stdout:

{
  "schemaVersion": 1,
  "status": "ok",
  "outputs": ["/Users/me/Pictures/photo.jpg"],
  "jobs": [
    {
      "input": "/Users/me/Pictures/photo.heic",
      "outputs": ["/Users/me/Pictures/photo.jpg"],
      "state": "Succeeded"
    }
  ],
  "allowance": { "used": 3, "limit": 50 }
}

Field	Meaning
`schemaVersion`	`1`. Fields are only ever added.
`status`	`ok`, `partial` (some jobs failed) or `error`.
`outputs`	Absolute paths of every file written.
`jobs`	One entry per input: `input`, `outputs`, `state` and, when it failed, `error`.
`allowance`	Free runs used and the limit, on an npm or .NET tool install without a plan.
`updateAvailable`	A newer version, when there is one. Run `filestarcli update` when it suits you.
`error`	When `status` is `error`: `code`, `message`, and where they apply `forUser`, `hint`, `url` and `next`.

In error, forUser is a sentence written for the person: pass it on unchanged. next is the exact command to run next, hint says what to try, and url is a link for the person.

Exit codes

Code	Meaning
0	Everything worked.
1	Some jobs failed. The files that were written are in `outputs`.
2	Usage error: an unknown option or a missing argument.
3	Unknown file type, or no skill for this command and file.
4	A paid plan is required.
5	The free runs on this computer are used up.
6	Network or service error.
7	Cancelled or timed out. Half-written outputs are removed.

Error codes

Code	What to do
`UsageError`	Fix the command line. `filestarcli <command> --help` ends with examples.
`UnknownFileType`	Filestar does not recognise the file. Check it with `filestarcli detect <file> --candidates`.
`NoSkill`	No skill does this for this file type. Run `filestarcli skills -i <file>` to see what is possible.
`ParameterInvalid`	A parameter name or value is wrong. The message names it and its allowed values; see `skills describe`.
`PlanRequired`	This needs a plan (cloud skills, batches). Show the person `forUser` and the link.
`CliAllowanceUsed`	Show the person `forUser` and the link, then run `next` (`filestarcli upgrade --wait`). Do not retry, reinstall or switch tools to get around it.
`NotEnoughCredits`	The plan's cloud credits are used up. Show the person `forUser`.
`NetworkError`	No connection to Filestar's services. Try again later; in a sandbox, allow network access.
`ServiceError`	A Filestar service answered with an error. Try again later.
`JobFailed`	The skill ran and failed for this file. The job's `error` says why.
`Cancelled`	The run was stopped.
`Timeout`	The run took longer than `--timeout`.

Parameters

filestarcli skills describe "resize" -i photo.png --json lists the parameters of the skill that would run, and its alternatives:

{
  "schemaVersion": 1,
  "command": "resize",
  "skill": { "id": "…", "plugin": "…", "local": true, "cloud": false, "platforms": ["win-x64", "osx-arm64", "linux-x64"] },
  "alternatives": [],
  "parameters": [
    { "name": "Width", "kind": "Number", "type": "integer", "label": "Width", "default": 800, "minimum": 1, "required": false }
  ]
}

Each parameter has a name, a kind (Text, Number, Slider, Select, Options, Check, Color, Font or Alignment), a JSON type, a label, required, and where they apply description, default, minimum, maximum, step and enum (a list of value and label). Pass them with -p Name:value or --parameters-json. The example above is illustrative: ask skills describe for the real parameters.

Environment

Variable	What it does
`FILESTAR_LICENSE_KEY`	Registers the CLI with this licence key on its first run. For CI, containers and sandboxes.
`FILESTAR_USER_AGENT`	The agent's name, when `--user-agent` is not passed.
`NO_COLOR`	No colour in the output.