---
version: 1.0.0
updated: 2026-03-12
tags: [workspace, list, repos]
---

# Command: list-repos

Lista todos los workspaces registrados en la base de datos local con soporte de filtro y ordenamiento.

## Para el usuario

### Cuándo usar este comando

Usar para inspeccionar rápidamente los workspaces disponibles:

- Ver qué repos existen localmente
- Verificar estado de sincronización con Gitea
- Encontrar un workspace por nombre o descripción
- Ver URLs de Gitea para clonar en otra máquina

### Prerequisitos

- Issue 0007 completado (base de datos SQLite)
- Feature flag `workspace_commands` habilitado

### Sintaxis

```bash
/workspace:list-repos
/workspace:list-repos --filter <term>
/workspace:list-repos --sort <field>
```

### Ejemplos

```bash
# Listar todos los workspaces
/workspace:list-repos

# Filtrar por nombre o descripción
/workspace:list-repos --filter pipeline

# Ordenar por nombre alfabético
/workspace:list-repos --sort name

# Filtrar y ordenar combinados
/workspace:list-repos --filter etl --sort name
```

### Salida esperada

```
Workspaces locales (4 repos):

┌────────────────────────┬─────────────────────────────┬────────────────┬─────────────┐
│ Nombre                 │ Descripción                 │ Última act.    │ Estado      │
├────────────────────────┼─────────────────────────────┼────────────────┼─────────────┤
│ my-etl-pipeline        │ ETL para datos ventas       │ hace 2 días    │ ✓ activo    │
│ data-pipeline-v2       │ Pipeline v2 mejorado        │ hace 1 sem.    │ ✓ activo    │
│ ml-training-service    │ Servicio ML training        │ hace 3 días    │ ✓ activo    │
│ old-experiment         │ Experimento temporal        │ hace 2 meses   │ ✓ activo    │
└────────────────────────┴─────────────────────────────┴────────────────┴─────────────┘

URLs Gitea:
  - my-etl-pipeline: https://gitea-xxx.organic-machine.com/Bl4cksmith/my-etl-pipeline
  - data-pipeline-v2: https://gitea-xxx.organic-machine.com/Bl4cksmith/data-pipeline-v2
  - ml-training-service: https://gitea-xxx.organic-machine.com/Bl4cksmith/ml-training-service
  - old-experiment: (no disponible en Gitea)

Para trabajar en un workspace:
  cd workspaces/<nombre>
```

## Para Claude

### Precondiciones

Verificar antes de ejecutar:
- [ ] Feature flag `workspace_commands` habilitado en `dev/feature_flags.json`
- [ ] Base de datos inicializada (issue 0007 completado)

### Flujo de implementación

#### Paso 0: Verificar feature flag

Leer `dev/feature_flags.json`. Si `workspace_commands.enabled: false`, informar al usuario:

```
El comando /list-repos requiere que el feature flag 'workspace_commands' esté habilitado.
Editar dev/feature_flags.json y cambiar "enabled": true para workspace_commands.
```

#### Paso 1: Detectar argumentos

Parsear los argumentos del usuario:
- `--filter <term>` → filtrar por nombre/descripción (case-insensitive)
- `--sort <field>` → ordenar por campo (`name` o `date`, default: `date`)

#### Paso 2: Ejecutar vía `app.ListWorkspacesCommand`

El flujo completo está en `app/workspace_list.go`:

```go
// Listar todos:
err := app.ListWorkspacesCommand(config, "", "date")

// Filtrar:
err := app.ListWorkspacesCommand(config, "pipeline", "date")

// Filtrar y ordenar:
err := app.ListWorkspacesCommand(config, "etl", "name")
```

El comando hace automáticamente:
1. Obtener workspaces de SQLite (`shell.ListWorkspacesDB`)
2. Filtrar si hay `--filter` (`core.FilterWorkspaces` — función pura)
3. Ordenar (`core.SortWorkspaces` — función pura)
4. Formatear tabla ASCII (`core.FormatWorkspaceTable` — función pura)
5. Mostrar resultado con URLs de Gitea al final

#### Paso 3: Si no hay workspaces

Si la BD está vacía o el filtro no coincide con nada:

```
No hay workspaces registrados.
```

O si había filtro:
```
Workspaces que coinciden con 'pipeline':

No hay workspaces registrados.
```

Sugerir usar `/workspace:create-repo` para crear el primero o `/workspace:sync-repos` para importar desde Gitea.

### Decisiones de diseño

1. **Tabla ASCII con box-drawing**: Legible en cualquier terminal sin dependencias adicionales.
2. **Filtro case-insensitive**: Busca en slug, nombre y descripción.
3. **Ordenamiento por fecha por defecto**: Los más recientes primero (más útil en el día a día).
4. **URLs Gitea al final**: Separadas de la tabla para no saturar visualmente.
5. **Nombres truncados a 22 chars**: Evita tablas muy anchas.

### Manejo de errores

| Error | Causa | Solución |
|-------|-------|----------|
| "error al inicializar base de datos" | BD no creada | Ejecutar `dataforge init` |
| "error al listar workspaces" | Corrupción de BD | Ejecutar `dataforge workspace rebuild-db` |

## Troubleshooting

### No aparecen workspaces

La BD puede estar vacía. Opciones:
1. Crear un workspace: `/workspace:create-repo`
2. Importar desde Gitea: `/workspace:sync-repos`

### El filtro no encuentra nada

El filtro busca en slug, nombre y descripción (case-insensitive). Verificar:
- El término está bien escrito
- El workspace existe: ejecutar `/workspace:list-repos` sin filtro

### Tabla con formato incorrecto

Puede ocurrir si la terminal es muy estrecha. Usar una terminal de al menos 80 columnas de ancho.