Use Filestar With AI Agents

AI agents such as Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot CLI and Claude Desktop can use Filestar to convert, resize, compress, merge and inspect files. The agent runs the Filestar CLI (filestarcli) on your computer, so your files stay on your computer unless you choose a cloud skill.

Start in three commands

npm install -g filestar
filestarcli agent readme
filestarcli -i photo.heic -c "convert to jpg" --json --user-agent claude-code

1. npm install -g filestar installs the CLI, without the Filestar app. You can also use npx -y filestar, the .NET tool or the desktop app: see Get Started.
2. filestarcli agent readme prints everything an agent needs to know, as markdown: the commands, the JSON it gets back, the exit codes and what to do about each error.
3. The agent runs the conversion with --json and reads the paths of the files it wrote from the result.

To add Filestar to the agents on your computer in one step, run filestarcli agent install. It finds the agents you have, shows what it would add to each and asks before it writes anything. In the Filestar app, choose Help › Use With AI Agents….

Local by default

Filestar runs skills on the computer the agent runs on. Nothing is uploaded unless a skill runs in the cloud, and the CLI only uses cloud skills when it is told to. Agents should pass --cloud Disallowed when files must stay on the computer. See Privacy.

What it costs

An npm or .NET tool install gets 50 free skill runs on each computer, with no account. Local skills only, one file per run. After that, or for cloud skills and batches, a Filestar plan is needed. When the free runs are used up, the CLI gives the agent a link for you to open and choose a plan; the purchase is tied to your computer, so nobody has to copy a licence key. See Plans and Limits.

The CLI that comes with the Filestar app works as before: it uses the app's plan.

Supported agents

A skill tells an agent with a shell how to run filestarcli and costs little context. The MCP server (filestarcli mcp) gives agents without a shell the same abilities as tools.

Rules for agents

• Run filestarcli agent readme once per session and follow it.
• Pass --json and --user-agent <your name>, and read the exit code.
• Never use --cloud Forced unless the person asked for it.
• When the result says CliAllowanceUsed (exit code 5), show the person the forUser text and the link, then run the next command. Do not retry, reinstall or switch tools to get around it.

The commands, JSON and exit codes are in the CLI Reference.