# CLI Commands

Spaces are managed through two interfaces: the `aroom space` CLI subcommand and the `/space` REPL command. Both share the same underlying storage and logic.

## CLI: `aroom space`

Terminal commands for managing spaces outside of a chat session.

### `aroom space list`

List all registered spaces with origin, conversation count, and active marker.

```bash
$ aroom space list
┌──────────────┬────────┬───────┬────────┐
│ Name         │ Origin │ Convs │ Active │
├──────────────┼────────┼───────┼────────┤
│ backend-api  │ local  │    12 │   *    │
│ ml-pipeline  │ global │     3 │        │
└──────────────┴────────┴───────┴────────┘
```

- **Origin**: `local` if the space file is in a project directory, `global` if under `~/.anteroom/spaces/`
- **Convs**: number of conversations in that space
- **Active**: `*` marks the currently active space

If no spaces exist, shows a hint:

```
No spaces found. Create one with: aroom space create <name>
```

### `aroom space create <name>`

Create a new local space file at `.anteroom/space.yaml` in the current directory.

```bash
$ cd ~/projects/acme
$ aroom space create acme-platform
Created space: acme-platform
  Space file: /home/dev/projects/acme/.anteroom/space.yaml
```

**What happens:**

1. Creates `.anteroom/space.yaml` in the current directory with a self-documenting YAML template
2. The template includes commented examples for repos, packs, sources, instructions, and config
3. Validates the space name
4. Checks for name conflicts
5. Creates the space record in the database with a SHA-256 file hash

**Errors:**

```bash
$ aroom space create -bad-name
Error: Invalid space name: '-bad-name'

$ aroom space create backend-api
Error: Space 'backend-api' already exists

$ aroom space create my-project
Error: Space file already exists: /home/dev/projects/acme/.anteroom/space.yaml
```

### `aroom space init`

Create a new local space file, deriving the name from the current directory.

```bash
$ cd ~/projects/my-project
$ aroom space init
Created space: my-project
  Space file: /home/dev/projects/my-project/.anteroom/space.yaml
```

Equivalent to `aroom space create <dirname>` where `<dirname>` is the name of the current directory (e.g., in `/home/dev/my-project`, the space name is `my-project`). Same validation and behavior as `space create`.

### `aroom space show <name>`

Display details about a space.

```bash
$ aroom space show backend-api
backend-api
  ID:          a1b2c3d4-5678-9abc-def0-123456789abc
  File:        /home/dev/.anteroom/spaces/backend-api.yaml
  Hash:        a1b2c3d456789abc...
  Last loaded: 2025-01-15T10:30:00+00:00
  Created:     2025-01-10T08:00:00+00:00
```

### `aroom space delete <name>`

Remove a space and all its associated data.

```bash
$ aroom space delete backend-api
Deleted space: backend-api
```

**What's cleaned up:**

- Space record from `spaces` table
- All mapped paths from `space_paths` table
- Pack attachments scoped to this space
- Conversations and folders are unlinked (set to `space_id = NULL`), not deleted

### `aroom space refresh <name>`

Re-read the space file and update the stored hash.

```bash
$ aroom space refresh backend-api
Refreshed: backend-api (hash updated)
```

If the file hasn't changed:

```
Space file unchanged — nothing to refresh.
```

Note: When a space is active in a REPL session, Anteroom automatically monitors the space file via mtime polling (default 5-second interval). Manual refresh is only needed outside of an active session or to force an immediate reload. See [Hot Reload](hot-reload.md) for details.

### `aroom space clone <name>`

Clone all repos defined in the space file.

```bash
$ aroom space clone backend-api
Repos root directory
  [/home/dev/.anteroom/spaces/backend-api/repos]: /home/dev/projects/acme
  Saved repos root to /home/dev/.anteroom/spaces/backend-api.local.yaml
  OK   https://github.com/acme/api-server.git → /home/dev/projects/acme/api-server
  OK   https://github.com/acme/shared-libs.git → /home/dev/projects/acme/shared-libs
```

**Repos root resolution:**

1. If the local config (`.local.yaml`) has `repos_root`, use it
2. Otherwise, prompt the user (default: `~/.anteroom/spaces/<name>/repos/`)
3. In non-interactive mode (piped stdin), use the default without prompting
4. Save the chosen root to the local config

**Clone behavior:**

- Uses `git clone --depth=1` for fast shallow clones
- Skips repos that already exist at the destination
- URL scheme validation rejects `ext::`, `file://`, and other unsafe schemes
- 120-second timeout per repo
- Credential-sanitized error messages on failure
- Successfully cloned paths are synced to `space_paths` in the database

### `aroom space map <name> <directory>`

Map a local directory to a space for auto-detection.

```bash
$ aroom space map backend-api /home/dev/projects/acme/custom-service
Mapped: /home/dev/projects/acme/custom-service → backend-api
```

Use this when you have a repo that wasn't cloned via `aroom space clone` but should be associated with the space. Starting `aroom chat` from this directory (or any subdirectory) will auto-detect the space.

**Validation:**

- Directory must exist
- Duplicate paths are silently skipped

### `aroom space move-root <name> <path>`

Change where repos are stored for a space (per-machine setting).

```bash
$ aroom space move-root backend-api /home/dev/new-location
Repos root updated: /home/dev/new-location
```

Updates the `repos_root` in the local config file (`.local.yaml`). The directory must exist. This does **not** move any files — it only changes where future `aroom space clone` operations will place repos.

## REPL: `/space`

In-session commands for managing spaces during a chat.

### `/space` or `/space list` or `/spaces`

List all spaces with origin, conversation counts, and active markers.

```
> /spaces
Spaces:
  * backend-api — local — 12 conversations
    ml-pipeline — global — 3 conversations
```

The active space is marked with `*`. Origin shows whether the space file is `local` (in a project directory) or `global` (in `~/.anteroom/spaces/`).

### `/space switch <name>`

Switch to a different space within the current session.

```
> /space switch ml-pipeline
Active space: ml-pipeline
```

**What happens:**

1. Looks up the space by name
2. Sets it as the active space
3. Updates the current conversation's `space_id`
4. Injects the space's instructions into the system prompt

### `/space show` or `/space show <name>`

Display space details. Defaults to the active space if no name is given.

```
> /space show
backend-api
  File:  /home/dev/.anteroom/spaces/backend-api.yaml
  Convs: 12
  Paths:
    https://github.com/acme/api-server.git → /home/dev/projects/acme/api-server
    https://github.com/acme/shared-libs.git → /home/dev/projects/acme/shared-libs
```

### `/space refresh`

Re-read the active space's YAML file and update instructions.

```
> /space refresh
Refreshed: backend-api
```

Reloads the space file, updates the stored hash, and re-injects instructions if they changed. If the file has invalid YAML, the refresh is silently skipped and the previous config remains active.

### `/space clear`

Deactivate the current space.

```
> /space clear
Cleared space: backend-api
```

Removes the space association from the current conversation and strips space instructions from the system prompt.

### `/space create <name>`

Create a new local space file from within the REPL.

```
> /space create new-project
Created space: new-project
  Space file: /home/dev/projects/new-project/.anteroom/space.yaml
```

Same behavior as `aroom space create` — creates `.anteroom/space.yaml` in the current directory with a self-documenting template.

### `/space init`

Create a new local space file, deriving the name from the current directory.

```
> /space init
Created space: my-project
  Space file: /home/dev/projects/my-project/.anteroom/space.yaml
```

Same behavior as `aroom space init`.

### `/space sources`

List sources directly linked to the active space.

```
> /space sources
Sources in backend-api:
  API Spec   text · 3f8a1b2c...
  Runbook    file · 9d4e5f6a...
```

Requires an active space (`/space switch <name>` first). Shows only direct source links, not sources present via group or tag links.

### `/space link-source <query>`

Link a source to the active space by title or ID.

```
> /space link-source API Spec
Linked 'API Spec' to space 'backend-api'
```

Searches sources by exact title match first, then partial match, then exact ID. Creates a direct source link in `space_sources`.

### `/space unlink-source <query>`

Unlink a source from the active space.

```
> /space unlink-source API Spec
Unlinked 'API Spec' from space 'backend-api'
```

Only removes direct source links. If the source is present via a group or tag link, it will remain in the space's resolved source set.

## Auto-Detection

When you start `aroom chat` from a directory mapped to a space (either via `clone` or `map`), Anteroom auto-detects the space:

```bash
$ cd /home/dev/projects/acme/api-server
$ aroom chat
Space: backend-api
>
```

Auto-detection walks up parent directories, so subdirectories also match:

```
~/projects/acme/api-server/        → detects "backend-api"
~/projects/acme/api-server/src/    → detects "backend-api" (walks up)
~/projects/acme/api-server/src/controllers/  → detects "backend-api" (walks up)
~/projects/other/                  → no space detected
```

The deepest (most specific) mapped path wins if multiple spaces overlap.

## CLI Flag: `--space`

Force a specific space when starting a chat session:

```bash
$ aroom chat --space ml-pipeline
```

This overrides auto-detection.

## Command Summary

| Action | CLI | REPL |
|--------|-----|------|
| List spaces | `aroom space list` | `/spaces` or `/space list` |
| Create space | `aroom space create <name>` | `/space create <name>` |
| Init space (auto-name) | `aroom space init` | `/space init` |
| Show details | `aroom space show <name>` | `/space show [name]` |
| Delete space | `aroom space delete <name>` | — |
| Refresh file | `aroom space refresh <name>` | `/space refresh` |
| Clone repos | `aroom space clone <name>` | — (terminal operation) |
| Map directory | `aroom space map <name> <dir>` | — (terminal operation) |
| Move repos root | `aroom space move-root <name> <path>` | — (terminal operation) |
| Switch space | — | `/space switch <name>` |
| Clear space | — | `/space clear` |
| List space sources | — | `/space sources` |
| Link source | — | `/space link-source <query>` |
| Unlink source | — | `/space unlink-source <query>` |

## Next Steps

- [Quickstart](quickstart.md) — try these commands hands-on
- [API Reference](api-reference.md) — HTTP equivalents for web UI
- [Repo Management](repo-management.md) — deep dive on cloning and mapping
