fast-folder-cli

⚡ fast-folder-cli

Encuentra cualquier carpeta de tu PC en segundos, directamente desde la terminal.

fast-folder-cli es una herramienta de línea de comandos escrita en Go que recorre el disco de forma concurrente para localizar carpetas por nombre, pensada para reemplazar la lenta búsqueda del Explorador de archivos de Windows.

> fast-folder-cli -n proyecto

Buscando "proyecto" en C:\Users\usuario (ocultas/sistema: excluidas)

  [1] C:\Users\usuario\Documents\Proyecto-Final
  [2] C:\Users\usuario\Desktop\escuela\mi-proyecto
  [3] C:\Users\usuario\source\repos\proyecto-api

────────────────────────────────────────────────────────────────
Resultados : 3 carpetas encontradas
Analizadas : 27,972 carpetas
Tiempo     : 854 ms

✨ Lo que lo hace diferente

📌 El problema

Buscar una carpeta con el cuadro de búsqueda del Explorador de Windows suele ser una experiencia frustrante:

• Depende del índice de Windows Search. Fuera de las ubicaciones indexadas (otras unidades, AppData, ProgramData, carpetas de proyectos...) el Explorador recorre el disco de forma secuencial y los resultados aparecen a cuentagotas.
• Busca de más. Examina archivos, contenido y propiedades aunque solo quieras una carpeta.
• No es automatizable. No puedes usarlo desde un script ni encadenarlo con otras herramientas.
• Las alternativas en consola son lentas. dir /s /b /ad y Get-ChildItem -Recurse recorren el árbol en un único hilo.

✅ La solución

📊 Rendimiento

Búsqueda de una carpeta en todo el perfil de usuario (%USERPROFILE%, incluyendo carpetas ocultas: ~149,000 carpetas), en Windows 11 con un procesador de 8 núcleos y SSD:

Ambas encontraron las mismas 4 carpetas, pero fast-folder-cli fue ~8.7 veces más rápido. Sin carpetas ocultas (el modo por defecto) el mismo perfil se recorre en menos de 1 segundo. Los tiempos dependen del disco y de la caché del sistema de archivos: la segunda búsqueda suele ser más rápida.

🛠️ Instalación

Requiere Windows 10 u 11 de 64 bits (x64 o ARM64).

⚠️ Si tu Windows 11 tiene Smart App Control activado, no podrás ejecutar fast-folder-cli. Consulta Si Windows bloquea el programa antes de instalar.

🧙 Asistente de instalación (recomendado)

1. Descarga fast-folder-cli-setup.exe.
2. Ábrelo y sigue los pasos: licencia → carpeta → opciones → Instalar.
3. Abre una terminal nueva y escribe fast --help. En la última pantalla puedes marcar Abrir una terminal para probar fast-folder-cli para hacerlo directamente.

El asistente:

• Instala la versión adecuada para tu equipo (x64 o ARM64) en %LOCALAPPDATA%\Programs\fast-folder-cli, sin permisos de administrador.
• Agrega esa carpeta al PATH de tu usuario (opción marcada por defecto) sin alterar el resto de entradas.
• Crea el atajo fast (opción marcada por defecto), para escribir fast -n proyecto en lugar de fast-folder-cli -n proyecto.
• Instala el comando fcd para buscar una carpeta y entrar en ella.
• Agrega Buscar carpetas aquí al menú contextual del Explorador (opción marcada por defecto).
• Se registra en Configuración → Aplicaciones → Aplicaciones instaladas, desde donde se desinstala. Para actualizar, basta con ejecutar el asistente de una versión nueva.

⚠️ El asistente no está firmado digitalmente, así que la primera vez Windows SmartScreen puede mostrar "Windows protegió su PC": pulsa Más información → Ejecutar de todas formas. Si en cambio Windows bloquea el archivo sin darte esa opción, es Smart App Control: consulta Si Windows bloquea el programa.

⚡ Desde la terminal, con un solo comando

Abre PowerShell y ejecuta:

irm https://raw.githubusercontent.com/AnthonyCZ6/fast-folder-cli/main/install.ps1 | iex

Eso es todo: ya puedes usar fast-folder-cli en esa misma ventana. El script:

• Detecta si tu equipo es x64 o ARM64 y descarga el ejecutable de la última versión.
• Comprueba las sumas SHA-256 antes de instalar.
• Lo copia en %LOCALAPPDATA%\Programs\fast-folder-cli, junto con el atajo fast y el comando fcd, y agrega esa carpeta al PATH de tu usuario, sin permisos de administrador y sin alterar el resto del PATH.
• Agrega Buscar carpetas aquí al menú contextual del Explorador.

Con Go

Si tienes Go 1.26 o superior (winget install GoLang.Go):

go install github.com/AnthonyCZ6/fast-folder-cli@latest

El ejecutable se instala en %USERPROFILE%\go\bin, carpeta que el instalador de Go ya agrega al PATH.

Descarga manual

1. Descarga el .exe de tu equipo desde la última versión:

   Equipo	Archivo
   Windows x64 (procesadores Intel o AMD, la mayoría de los equipos)	fast-folder-cli-windows-amd64.exe
   Windows ARM64 (procesadores Snapdragon, Surface Pro X)	fast-folder-cli-windows-arm64.exe

2. Renómbralo a fast-folder-cli.exe y guárdalo en una carpeta permanente, por ejemplo %LOCALAPPDATA%\Programs\fast-folder-cli.

3. Agrega esa carpeta al PATH (siguiente apartado).

⚠️ Los ejecutables no están firmados digitalmente, así que Windows SmartScreen o tu antivirus pueden mostrar una advertencia la primera vez, y Smart App Control los bloquea (consulta Si Windows bloquea el programa). Para comprobar que el archivo es el original, compara Get-FileHash .\fast-folder-cli.exe con el valor de checksums.txt publicado en la versión. El instalador de un solo comando hace esta comprobación por ti.

Agregar al PATH de Windows

1. Pulsa Win + R, escribe SystemPropertiesAdvanced y pulsa Enter.
2. Haz clic en Variables de entorno....
3. En Variables de usuario, selecciona Path → Editar → Nuevo y pega la ruta de la carpeta.
4. Acepta todas las ventanas y abre una terminal nueva (el PATH solo se lee al iniciarla).

Comprueba que funciona con:

fast-folder-cli --version

Compilar desde el código

Requiere Go 1.26 o superior:

git clone https://github.com/AnthonyCZ6/fast-folder-cli.git
cd fast-folder-cli
go build -trimpath -ldflags "-s -w -X main.version=1.0.0" -o fast-folder-cli.exe .

Compilación cruzada desde Linux o macOS (también compila allí, con funciones limitadas):

GOOS=windows GOARCH=amd64 go build -trimpath -ldflags "-s -w" -o fast-folder-cli.exe .
GOOS=windows GOARCH=arm64 go build -trimpath -ldflags "-s -w" -o fast-folder-cli-arm64.exe .

💡 Atajo fast y comando fcd: el asistente y el script de instalación los crean automáticamente. Si instalas con Go o a mano, copia fast-folder-cli.exe como fast.exe y shell/fcd.ps1 y shell/fcd.cmd en la misma carpeta.

Si Windows bloquea el programa

Los ejecutables de fast-folder-cli todavía no están firmados digitalmente. Con Smart App Control activado, Windows 11 no deja ejecutar programas sin firma ni reputación, así que la instalación termina sin errores, pero al escribir fast aparece un error como este:

Program 'fast-folder-cli.exe' failed to run: An Application Control policy has blocked this file

En Windows en español, el mensaje indica que una directiva de Control de aplicaciones bloqueó el archivo. Ocurre con cualquier método de instalación, incluso si lo compilas tú mismo.

Para saber si Smart App Control está activado, abre Seguridad de Windows → Control de aplicaciones y navegador → Configuración de Smart App Control, o ejecuta en PowerShell:

(Get-MpComputerStatus).SmartAppControlState   # On = bloquea; Eval u Off = no bloquea

A diferencia de SmartScreen, Smart App Control no ofrece Ejecutar de todas formas ni permite excepciones para un programa concreto. Mientras no haya versiones firmadas, la única forma de usar fast-folder-cli es desactivarlo. Antes de hacerlo, ten en cuenta que protege a todo el sistema. Desde la actualización de abril de 2026 (KB5083769) se puede volver a activar sin reinstalar Windows; en versiones anteriores de Windows 11, una vez desactivado, solo se podía recuperar reinstalando.

🚀 Uso

Si instalaste con el asistente o el script, puedes usar el atajo fast en lugar del nombre completo fast-folder-cli. Tras instalar, abre una terminal nueva: las que ya estaban abiertas no ven el PATH actualizado.

⌨️ Modo interactivo (con las flechas)

Disponible desde la versión 1.1.0. Escribe solo:

fast

y se abre una pantalla de búsqueda que se maneja sin escribir comandos:

 fast-folder-cli   v1.2.0

 ► Buscar     cancion
   Ubicación    Documentos           C:\Users\usuario\Documents
   Tipo         Carpetas             cualquier carpeta cuyo nombre coincida
   Modificada   Cualquiera           fecha de modificación de la carpeta
   Ocultas      No                   carpetas ocultas y de sistema

 ↑↓ moverse   ←→ cambiar opción   Enter buscar   Esc salir

1. Escribe el nombre (o parte del nombre) de la carpeta. No hace falta poner acentos.
2. Con ↓ baja a Ubicación y elige dónde buscar con ← →: tu perfil, Escritorio, Documentos, Descargas, la carpeta actual, AppData, ProgramData o cualquier unidad (C:, D:...).
3. En Tipo elige Proyectos para buscar solo carpetas de proyectos; así el nombre es opcional y, sin él, aparecen todos.
4. En Modificada elige Hoy, Ayer, Últimos 7 días o Últimos 30 días para ver solo las carpetas modificadas en ese periodo.
5. En Ocultas actívalas si también quieres buscar en carpetas ocultas y de sistema.
6. Pulsa Enter. Los resultados aparecen conforme se encuentran:

 fast-folder-cli   "cancion" en C:\Users\usuario\Documents

 ► Canción final           C:\Users\usuario\Documents\música
   Canciones-2024          C:\Users\usuario\Documents\escuela

 2 carpetas encontradas · 1,284 analizadas · 1/2 · 38 ms

 ↑↓ moverse   Enter abrir en el Explorador   ← nueva búsqueda   Esc salir
 c copiar ruta   v VS Code   t terminal   d tamaño y fecha

🚪 Entrar en una carpeta con fcd

Disponible desde la versión 1.2.0. Un programa no puede cambiar la carpeta de la terminal que lo abrió, así que el asistente y el script de instalación agregan el comando fcd (para PowerShell y para el Símbolo del sistema), que sí puede:

fcd tesis

Abre el modo interactivo con la búsqueda de tesis; al elegir una carpeta con Enter, la terminal queda dentro de ella. fcd acepta las mismas opciones que fast-folder-cli: fcd -p D: proyecto, fcd --projects, fcd -m ayer... Sin argumentos abre el formulario vacío. Si no eliges ninguna carpeta, fcd termina con el mismo código de salida que fast-folder-cli (por ejemplo, 2 si una opción no es válida).

Si PowerShell dice que la ejecución de scripts está deshabilitada en este sistema, fcd no puede funcionar con la directiva de ejecución actual. Puedes permitir los scripts locales solo para tu usuario con Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, o usar fcd desde el Símbolo del sistema.

🖱️ Menú contextual del Explorador

Disponible desde la versión 1.2.0. Haz clic derecho en el fondo de una carpeta (o sobre una carpeta) y elige Buscar carpetas aquí (fast-folder-cli): se abre el modo interactivo con esa carpeta como ubicación. En Windows 11 la opción está en Mostrar más opciones (o pulsando Mayús + F10).

El asistente la agrega si dejas marcada su casilla y el script de instalación la agrega salvo que uses -NoContextMenu. Al desinstalar se quita. Por dentro ejecuta fast-folder-cli --path "<carpeta>", que sin término abre el modo interactivo.

Con comandos (para scripts)

fast-folder-cli -n <término> [-p <ruta>] [opciones]
fast-folder-cli <término> [opciones]
fast-folder-cli --projects [término] [opciones]

Con un término (o con --projects o -m), la herramienta funciona como un comando normal: imprime los resultados y termina, así que se puede usar en scripts y redirigir su salida. Si solo indicas opciones, como fast -p D:, abre el modo interactivo con ellas.

Si tienes otro programa llamado fast (por ejemplo, el medidor de velocidad de npm fast-cli), el que aparezca primero en el PATH tendrá prioridad; el nombre completo fast-folder-cli siempre funciona.

Banderas

Las banderas pueden escribirse en cualquier orden, antes o después del término, y con = o espacio: --name=proyecto equivale a --name proyecto.

Ejemplos

# Buscar en tu perfil de usuario
fast-folder-cli -n proyecto

# Término como argumento posicional (con espacios, entre comillas)
fast-folder-cli "mis documentos escolares"

# Buscar en AppData incluyendo carpetas ocultas
fast-folder-cli -n discord -p %APPDATA% -a

# Buscar en otra unidad y abrir el primer resultado en el Explorador
fast-folder-cli -n "tesis*" -p D: -o

# Buscar datos de aplicaciones en ProgramData
fast-folder-cli --name nvidia --path %PROGRAMDATA% --all

# Guardar los resultados en un archivo
fast-folder-cli -n node_modules -p C:\dev > resultados.txt

# Sin acentos: encuentra "Canción", "canciones"...
fast-folder-cli cancion

# Todos tus proyectos, y los de Python modificados esta semana
fast-folder-cli --projects
fast-folder-cli --projects -m semana

# Las carpetas de Documentos que tocaste ayer
fast-folder-cli -m ayer -p %USERPROFILE%\Documents

# Cuánto ocupa cada node_modules de C:\dev
fast-folder-cli node_modules --size -p C:\dev

Buscar proyectos

--projects (o Tipo: Proyectos en el modo interactivo) busca carpetas que contienen alguno de estos archivos o carpetas, y muestra el tipo junto a cada una:

> fast --projects -p C:\Users\usuario\Documents

  [1] C:\Users\usuario\Documents\escuela\web  (Node.js)
  [2] C:\Users\usuario\Documents\escuela\api  (Go, Python)
  [3] C:\Users\usuario\Documents\juegos\plataformas  (Unity)

Con un término, solo aparecen los proyectos cuyo nombre coincide (--projects api). El interior de un proyecto no se recorre (node_modules, bin, .git...), lo que hace la búsqueda rápida; por eso un proyecto dentro de otro no aparece. La carpeta raíz de la búsqueda nunca cuenta como proyecto, para que un package.json suelto en tu carpeta personal no oculte todo lo demás.

Filtrar por fecha de modificación

-m (o el campo Modificada del modo interactivo) deja solo las carpetas modificadas en un periodo. Se puede usar con o sin término:

Windows cambia la fecha de una carpeta cuando se crea, borra o renombra algo directamente dentro de ella (también al guardar archivos con muchos editores, que reemplazan el archivo al guardar), pero no al editar un archivo de una subcarpeta.

Cuánto ocupa cada carpeta

--size suma el tamaño de los archivos de cada carpeta encontrada (incluidas sus subcarpetas ocultas, sin seguir enlaces) y las muestra ordenadas de mayor a menor, con el total al final:

> fast node_modules --size -p C:\dev

     1.2 GB  C:\dev\tienda\node_modules
     350 MB  C:\dev\blog\node_modules
      48 MB  C:\dev\api\node_modules

────────────────────────────────────────────────────────────────
Resultados : 3 carpetas encontradas
Tamaño     : 1.6 GB en total (98,412 archivos)

Con --size no se busca dentro de las carpetas encontradas, para no contar dos veces los node_modules anidados. Si pulsas Ctrl+C antes de que termine, se muestran las carpetas encontradas hasta ese momento, sin tamaño (estaría incompleto). En el modo interactivo, la tecla D muestra el tamaño de la carpeta seleccionada.

Reglas de coincidencia

Las búsquedas no distinguen mayúsculas de minúsculas, igual que Windows, ni acentos: cancion encuentra Canción, pinguino encuentra Pingüino y ano encuentra Año 2024 (la ñ se trata como n).

Sin comodines, el término puede aparecer en cualquier parte del nombre. Con comodines (*, ?, [ ]) el patrón debe cubrir el nombre completo de la carpeta.

Variables de entorno y rutas especiales

Funciona con cualquier variable definida en el sistema. PowerShell no expande la sintaxis %VAR%, así que fast-folder-cli la resuelve por su cuenta; en PowerShell también puedes usar la sintaxis nativa (-p $env:APPDATA).

Carpetas ocultas y de sistema

Por defecto se omiten (ni se muestran ni se recorren):

• Carpetas con el atributo Oculto o Sistema de Windows (AppData, $Recycle.Bin, System Volume Information, ...).
• Carpetas cuyo nombre empieza por punto (.git, .vscode, .cache, ...).

Usa -a / --all para incluirlas. La carpeta raíz indicada con --path siempre se recorre, aunque esté oculta: -p %APPDATA% funciona sin --all.

Códigos de salida

Útiles para scripts, siguiendo la convención de grep:

⚙️ Cómo funciona

             ┌────────────────── semáforo (4 × núcleos) ──────────────────┐
  raíz ──►  walk(dir) ──► ¿hay un slot libre? ──sí──► nueva goroutine: walk(subdir)
                                   │
                                   └──no──► walk(subdir) en la goroutine actual

1. Concurrencia acotada sin interbloqueos. Cada subcarpeta se entrega a una goroutine nueva si hay capacidad libre en el semáforo; si no, la goroutine actual la procesa en profundidad. Nunca hay más goroutines activas que el límite y ninguna se queda bloqueada esperando a otra.
2. Mínimas llamadas al sistema. Los atributos (oculto, sistema, reparse point) se leen de los datos que Windows ya devuelve al listar el directorio, sin consultas adicionales por carpeta. Las entradas no se ordenan, ahorrando trabajo en carpetas grandes.
3. Errores sin interrupciones. Un "Acceso denegado" solo incrementa el contador sin acceso; el resto del árbol se sigue recorriendo.
4. Resultados en tiempo real. Cada coincidencia se imprime en cuanto se encuentra; la salida se agrupa en un búfer que se vacía cuando no hay más resultados pendientes, para no ralentizar la consola cuando hay miles de coincidencias.
5. Enlaces seguros. Las uniones heredadas de Windows (por ejemplo AppData\Local\Application Data, que apunta a sí misma) provocarían un bucle infinito. Los enlaces se muestran si coinciden, pero nunca se recorren. Las carpetas de OneDrive sí se recorren con normalidad.

📁 Estructura del proyecto

fast-folder-cli/
├── .github/
│   ├── workflows/release.yml      # Pruebas, compilación y publicación de versiones
│   └── scripts/release-notes.sh   # Notas de versión a partir de los commits
├── installer/fast-folder-cli.iss  # Asistente de instalación (Inno Setup)
├── install.ps1                    # Instalador de un solo comando para Windows
├── shell/                         # Comando fcd para PowerShell (fcd.ps1) y cmd (fcd.cmd)
├── main.go                        # Punto de entrada
├── internal/
│   ├── cli/                       # Banderas, formato de salida y colores de consola
│   ├── tui/                       # Modo interactivo con flechas (Bubble Tea)
│   ├── query/                     # Qué se busca (término, proyectos, fecha): validación y descripción comunes a cli y tui
│   ├── search/                    # Búsqueda concurrente, coincidencia sin acentos, proyectos y tamaños
│   ├── period/                    # Periodos de fecha en español ("hoy", "semana", "7d")
│   ├── pathutil/                  # Resolución de %VARIABLES%, ~ y unidades
│   ├── launch/                    # Explorador, VS Code, terminal y portapapeles
│   └── humanize/                  # Formato de números ("52,341"), tamaños ("1.5 KB") y plurales
├── go.mod
├── LICENSE
└── README.md

🧪 Desarrollo

go test ./...     # pruebas unitarias (incluye pruebas específicas de Windows: atributos y junctions)
go vet ./...      # análisis estático
gofmt -l .        # comprobar formato

Para generar el asistente de instalación localmente, instala Inno Setup (6.7 o superior), deja los dos ejecutables en dist\ y ejecuta:

ISCC.exe /DAppVersion=1.0.0 installer\fast-folder-cli.iss   # genera dist\fast-folder-cli-setup.exe

Publicar una nueva versión

Las versiones se publican automáticamente con GitHub Actions (release.yml). Basta con crear y subir una etiqueta semántica:

git tag v1.1.0
git push origin v1.1.0

El workflow entonces:

1. Ejecuta las pruebas en Windows (con Go 1.26 y con la versión estable más reciente) y en Linux con el detector de condiciones de carrera (-race).
2. Compila fast-folder-cli-windows-amd64.exe y fast-folder-cli-windows-arm64.exe con la versión tomada de la etiqueta, e incrusta en ellos el nombre del producto y la versión (los que Windows muestra en Propiedades → Detalles) con go-winres. El workflow comprueba que esos datos coinciden con la versión en los tres ejecutables.
3. Genera el asistente fast-folder-cli-setup.exe con Inno Setup (versión y SHA-256 fijados en el workflow) y comprueba en Windows que se instala y desinstala correctamente en modo silencioso, igual que install.ps1 con los archivos recién compilados (-SourceDir): ejecutables, fcd y menú contextual.
4. Crea el release en GitHub con los tres ejecutables, los scripts de fcd, checksums.txt (SHA-256) y notas generadas a partir de los mensajes de commit, agrupados por tipo (feat, fix, docs...).
5. Instala la versión recién publicada con install.ps1 en un Windows limpio (Windows PowerShell 5.1 y PowerShell 7), la usa y la desinstala, para garantizar que el comando de instalación funciona.

Las etiquetas con sufijo (v1.2.0-rc.1) se publican como prerelease. Para comprobar que todo compila sin publicar nada, ejecuta el workflow a mano desde la pestaña Actions (Release → Run workflow): los ejecutables quedarán disponibles como artefacto y el instalador se probará con la última versión publicada.

🤝 Contribuir

1. Haz un fork del repositorio y crea una rama: git checkout -b feat/mi-mejora.
2. Asegúrate de que go test ./... y go vet ./... pasan.
3. Usa Conventional Commits en tus mensajes (feat:, fix:, docs:, refactor:...).
4. Abre un pull request describiendo el cambio.

📄 Licencia

Distribuido bajo la licencia MIT. Consulta el archivo LICENSE para más detalles.

Code signing policy

Los ejecutables para Windows (fast-folder-cli-windows-amd64.exe, fast-folder-cli-windows-arm64.exe y fast-folder-cli-setup.exe) todavía no están firmados digitalmente. Se compilan en GitHub Actions a partir del código de este repositorio (release.yml), y cada versión publica sus sumas SHA-256 en checksums.txt. Cuando haya versiones firmadas, la firma también se hará en GitHub Actions y cada una requerirá la aprobación manual del mantenedor.

• Committers and reviewers: @AnthonyCZ6
• Approvers: @AnthonyCZ6

Privacy policy: This program will not transfer any information to other networked systems unless specifically requested by the user or the person installing or operating it.

fast-folder-cli solo lee los nombres de las carpetas de tu equipo y no se conecta a internet. El instalador de un solo comando descarga el ejecutable desde GitHub porque tú lo ejecutas.

📬 Contacto

Anthony — autor y mantenedor

• GitHub: @AnthonyCZ6
• Reporta errores o propone mejoras en Issues.

Si esta herramienta te ahorra tiempo, ¡considera darle una ⭐ al repositorio!