Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

[Feature]: Make the filee command easier for scripts and AI agents to drive

Abierto
  • ¿Algo no está bien?
#753 1 comentario 0 reacciones 1 asignado Ver en GitHub

Los mantenedores suelen responder en 1 día

@SeoJCalive ya está trabajando en esto.

Desde el 29/10/2026.

Evaluación

Este issue todavía no se ha evaluado.

Descripción

enhancement
What would you like Filee to do?

Make a few small additions to the filee command so scripts and AI coding agents (Claude Code, Codex, Cursor, Copilot) can use an installed Filee as a local tool without parsing console text. Existing output stays as it is; these mostly add to it (the one change is in item 1).

  1. JSON for formats and presets: accept --json and print one JSON document. For formats <format>, list what it converts to now and what it would convert to with optional engines. Today --json is accepted there but ignored, and the text table comes out, so those two calls would start printing JSON instead.
  2. Why a file failed, as data: in convert --json, add the existing error key (for example error.no_route) to failed files. When a conversion only needs an optional engine, also list which engines would make it possible.
  3. Which engines converted a file (optional): the ids of the converters that actually ran for each file in convert --json (a route can have several steps, and it can change while running). Core would need to record them on FileResult, so only if you want it.
  4. A short guide for agents: one page telling an agent how to call filee (always --json and -o, exit code 0 means nothing failed so check converted/state/outputs, point the user to Settings → Engines when an engine is missing). It could be an Agent Skills SKILL.md in the repo, a short section on filee.sh/cli, or both.

1 and 2 are the main part. 4 would be written against them.

Why / when would you use it?

filee is already a good fit for this: it runs offline, needs no prompts, has convert --json and clear exit codes, and Setup puts it on PATH. The gaps are in the places where a program has to decide what to do next.

Can this file become X? Answering this means splitting text like:

Markdown (md, markdown) converts to:
  png, jpg, webp, ... pdf, docx, ... txtz
With optional engines (install them in Filee, Settings → Engines):
  hwp, pptx, pptm, ... tcr

Is it impossible, or does it just need an engine? Without optional engines, md → pptx (listed above as possible with an engine; Pandoc does it) fails the same way as txt → mp3, which no engine can do:

"error": "No engine can do this conversion (md \u2192 pptx)"
"error": "No engine can do this conversion (txt \u2192 mp3)"

A caller can't tell these apart from the conversion JSON alone; it has to parse the formats text or guess what to try next, instead of telling the user "install Pandoc in Settings → Engines". filee formats already knows the difference, but convert doesn't show it.

The same additions help plain shell and PowerShell scripts, not only AI tools.

Ideas for how it could work

A possible shape (names are up to you):

// filee formats md --json
{ "format": "md", "to": ["pdf", "docx", "html"], "withOptionalEngines": ["pptx", "mobi"] }

// a failed file in filee convert doc.md --to pptx --json
{ "source": "doc.md", "state": "failed", "outputs": [],
  "error": "No engine can do this conversion (md → pptx)",
  "errorKey": "error.no_route", "needsEngines": ["pandoc"] }
  • Compatibility: existing convert --json keys, states and exit codes stay as they are, and output without --json doesn't change. The only change is that formats --json and presets --json print JSON instead of ignoring the flag. Messages stay in English, as decided in #552. New behaviour gets tests in Filee.Cli.Tests.
  • Engine ids: the ids already used for engines and engine priority (pandoc, libreoffice, …). needsEngines would only name engines offered in Settings → Engines (the EngineDownloads.Packages list), never bundled or system parts like 7-Zip or the Windows JPEG XR codec. It's the missing ones on one route that works once they're installed (all of them together, not alternatives). The JSON list of "with optional engines" targets in item 1 would use the same rule.
  • No MCP server: a local MCP server would only wrap filee and be one more thing to maintain. With JSON output and exit codes the command can be used directly.
  • Not included: installing engines from the command line, and a --dry-run mode (1 and 2 cover most of what it would show).

I'd like to work on this myself. I'd send 1 and 2 together as one PR, then 3 and 4 separately if you want them. A few things I'd like your call on:

  1. Scope: is this okay to do, and how far (1–4)?
  2. Engines per file (3): worth recording them on FileResult in Core?
  3. Agent guide (4): in the repo as SKILL.md, on filee.sh/cli, or both?

Please let me know whether I can go ahead with this. If you have any thoughts, I'll take them into account.

Lenguaje dominante
C#
Estrellas
3.6k
Forks
192
Merge medio
7 h 20 min
PR fusionados (30 d)
320

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de KnifeLemon/Filee

Todos los issues de KnifeLemon/Filee

Issues similares

Más issues de C#

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.