|
1 | 1 | --- |
2 | 2 | name: filesmith |
3 | | -description: Use when the user asks to convert, compress, resize, upscale or remove the background of files, generate an image, or merge, split or extract from PDFs on this Windows machine - runs the local Filesmith CLI, never overwrites. |
| 3 | +description: Use when the user wants to do something to files on this PC, even phrased casually ("compress this image", "shrink this video", "make this a webp", "convert to jpg/pdf/mp4", "resize to 1920", "upscale this", "remove the background", "make me an image of...", "merge/split these PDFs", "pull the text out of this PDF"). Runs the local Filesmith CLI; never overwrites originals. |
4 | 4 | metadata: |
5 | 5 | filesmith-version: {{VERSION}} |
6 | 6 | --- |
7 | 7 |
|
8 | | -# Filesmith CLI |
| 8 | +# Filesmith |
9 | 9 |
|
10 | | -Filesmith is installed on this machine. Its command line runs the app's own engine and bundled tools (ffmpeg, ImageMagick, mutool, 7-Zip, LibreOffice, Ghostscript, Real-ESRGAN), works offline except for the AI tools' one-time setup, and writes NEW files next to each source (or into `--out`). It never overwrites anything. |
| 10 | +Local file toolkit on PATH as `filesmith` (full path if not found: `{{FILESMITH}}`). It writes NEW files next to each source, or into `--out <folder>`, and never overwrites. Run it from the Bash tool and always add `--json`. |
11 | 11 |
|
12 | | -## Run it |
| 12 | +| User says | Run | |
| 13 | +| ----------------------------- | ------------------------------------------------------ | |
| 14 | +| compress / shrink / smaller | `filesmith compress "<file>" --json` | |
| 15 | +| convert / make it a X | `filesmith convert "<file>" --to webp --json` | |
| 16 | +| resize / smaller dimensions | `filesmith resize "<file>" --width 1920 --json` | |
| 17 | +| upscale / enlarge / sharpen | `filesmith upscale "<file>" --factor 2 --json` | |
| 18 | +| remove / cut out background | `filesmith removebg "<file>" --json` | |
| 19 | +| make / generate an image | `filesmith generate "<prompt>" --json` | |
| 20 | +| merge / split / text from PDF | `filesmith pdf merge\|split\|extract-text "<pdf>" --json` | |
| 21 | +| what can it do / is it set up | `filesmith formats --json`, `filesmith doctor --json` | |
13 | 22 |
|
14 | | -`filesmith` is on PATH. If the shell cannot find it (a session started before Filesmith was installed), use the full path: `{{FILESMITH}}`. |
15 | | - |
16 | | -```bash |
17 | | -filesmith convert "photo.heic" --to jpg --json |
18 | | -filesmith compress "talk.mp4" --codec h265 --scale 50 --json |
19 | | -filesmith resize "hero.png" --width 1920 --json |
20 | | -filesmith upscale "old.jpg" --factor 2 --json |
21 | | -filesmith removebg "product.jpg" --fill white --json |
22 | | -filesmith generate "a red kettle on a table" --count 2 --json |
23 | | -filesmith pdf merge "a.pdf" "b.pdf" --json # pages in argument order |
24 | | -filesmith pdf split "thesis.pdf" --pages 1-3,10 --json |
25 | | -filesmith formats --json # every --to value, option and model |
26 | | -filesmith doctor --json # what is installed, what is missing |
27 | | -``` |
28 | | - |
29 | | -Every command has `--help`. Every flag, event field and error code: [reference.md](reference.md). |
| 23 | +Many files: pass several paths, a glob (`"*.png"`) or a folder (`--recursive` for subfolders). Add `--help` to any command for its options. |
30 | 24 |
|
31 | 25 | ## Rules |
32 | 26 |
|
33 | | -- **Always pass `--json`** and read stdout one JSON object per line. Ignore stderr. |
34 | | -- **Dry run first** (`--dry-run`) for bulk work (more than a handful of files, globs, folders, `--recursive`) and for anything slow or large (upscale, generate, setup). Show the user the planned outputs, then run the same command without `--dry-run`. Planned names are predictions; report the real names from the `done` events. |
35 | | -- **Quote every path.** In cmd a `%` inside an argument can be expanded; use Git Bash or PowerShell for such names. |
36 | | -- **Never run `filesmith setup` without the user's go-ahead.** It downloads up to several GB. On `SETUP_REQUIRED`, show the user the `hint` command and what it would download (`filesmith setup <tool> --dry-run --json`), then ask. |
37 | | -- **Outputs never replace inputs.** Report `output` paths from `done` events; never guess names. For predictable names, write into an empty `--out` folder. |
38 | | -- **Exit 1**: report each `error` event's `input`, `message` and `hint`. **Exit 2**: nothing ran; fix the arguments (the message names the flag and its valid values) instead of retrying. |
39 | | -- **Never run `filesmith setup remove ...`** (it deletes installed AI tools) unless the user asked for exactly that, and never add `--permanent` without their explicit yes. |
40 | | -- **Run it from the Bash tool** (Git Bash). Windows PowerShell 5.1 garbles non-ASCII paths in captured output. |
41 | | -- **Avoid AI jobs** (`upscale --model pid` or `comfy:...`, `generate`) while the user runs one in the app: both load the GPU. Do not install or update Filesmith while a CLI job runs: the installer closes every `Filesmith.exe`, the CLI included. |
42 | | - |
43 | | -## Reading results |
44 | | - |
45 | | -| `event` | Meaning | |
46 | | -| -------------------- | ---------------------------------------------------------------------------------------- | |
47 | | -| `run` | first line: command, version, dryRun, input count, resolved options | |
48 | | -| `plan` | dry run only: predicted `output`; `ready: false` with `code`, `message`, `hint` | |
49 | | -| `start`, `progress` | a job began; `pct` 0-100 or null, `etaSec` | |
50 | | -| `done` | `input`, `output`, `outputKind` (`file` or `dir`), `inSize`, `outSize` or `files` | |
51 | | -| `skipped` | not run and not a failure (`SAME_FORMAT`: already that format) | |
52 | | -| `error` | `code`, `message`, `hint` (an exact command when one exists) | |
53 | | -| `warning` | a flag had no effect, or a value was clamped | |
54 | | -| `summary` | last line: `ok`, `failed`, `skipped`, `canceled`, `exitCode` | |
55 | | - |
56 | | -Exit codes: `0` all ok or skipped, `1` some failed, `2` bad arguments or a missing requirement (nothing ran), `130` canceled. |
57 | | - |
58 | | -While a job runs, its output name is an empty placeholder next to a `*.filesmith-part*` file or folder; only the `done` event's `output` is a result. |
59 | | - |
60 | | -| `code` | What to do | |
61 | | -| ----------------------- | --------------------------------------------------------------------------- | |
62 | | -| `SETUP_REQUIRED` | Tell the user the `hint` (`filesmith setup ...`); run it only after a yes | |
63 | | -| `GPU_UNSUPPORTED` | That model needs an NVIDIA GPU; offer `--model photo` (any GPU) | |
64 | | -| `TOOL_MISSING` | Run `filesmith doctor --json` and report the failing check | |
65 | | -| `RAR_MISSING` | CBR and RAR output need WinRAR; offer `cbz` or `zip` | |
66 | | -| `UNSUPPORTED_KIND` | That file cannot take this operation; `filesmith formats --json` lists what can | |
67 | | -| `NOT_FOUND`, `NO_MATCH` | Check the path or the pattern | |
68 | | -| `OUT_DIR_MISSING` | `--out` is a file, or could not be created | |
69 | | -| `PASSWORD` | The archive is password-protected; ask the user | |
70 | | -| `USAGE` | Fix the arguments from the message | |
71 | | -| `TOOL_FAILED` | Report the message; the file may be damaged | |
72 | | - |
73 | | -## When something is missing |
| 27 | +- **Dry run** (`--dry-run`) first for bulk or slow jobs (upscale, generate); show the plan, then run. |
| 28 | +- **Read results** from stdout, one JSON object per line: `done` has `input`, `output`, `inSize`, `outSize`; `error` has `message` and `hint`; the last line is `summary`. Report the real `output` paths. |
| 29 | +- **Never run `filesmith setup ...` without asking.** On `SETUP_REQUIRED` show the user the `hint`; it downloads up to several GB. |
| 30 | +- **Exit codes:** `0` ok, `1` some files failed (report each error), `2` bad arguments, nothing ran (fix them, do not retry blindly). |
74 | 31 |
|
75 | | -Run `filesmith doctor --json`. Every check that is not `ok` has a `fix`: a command (ask first if it is `filesmith setup ...`) or an instruction for the user. |
| 32 | +Every flag, event, error code and safety rule: [reference.md](reference.md). |
0 commit comments