> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hellofriday.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> The friday command-line tool for managing spaces, agents, signals, and the Friday daemon.

The `friday` CLI is how you interact with Friday from the terminal. It's a thin HTTP client over `localhost:18080` — every subcommand maps to one or more daemon routes. Use it to manage spaces, trigger signals, send prompts, publish skills, and control the daemon.

## Setup

The installer puts the `friday` binary at `~/.friday/local/bin/friday`. Add that directory to your shell PATH.

<Tabs>
  <Tab title="zsh">
    Add to `~/.zshrc`:

    ```bash theme={null}
    export PATH="$HOME/.friday/local/bin:$PATH"
    ```

    Then reload:

    ```bash theme={null}
    source ~/.zshrc
    ```
  </Tab>

  <Tab title="fish">
    Run once:

    ```bash theme={null}
    fish_add_path ~/.friday/local/bin
    ```

    Or add to `~/.config/fish/config.fish`:

    ```bash theme={null}
    set -gx PATH $HOME/.friday/local/bin $PATH
    ```
  </Tab>

  <Tab title="bash">
    Add to `~/.bashrc`:

    ```bash theme={null}
    export PATH="$HOME/.friday/local/bin:$PATH"
    ```

    Then reload:

    ```bash theme={null}
    source ~/.bashrc
    ```
  </Tab>

  <Tab title="PowerShell">
    Add to your profile (`$PROFILE`):

    ```powershell theme={null}
    $env:PATH = "$env:USERPROFILE\.friday\local\bin;" + $env:PATH
    ```
  </Tab>
</Tabs>

Verify:

```bash theme={null}
friday version
```

## Spaces

### friday workspace list

List all registered spaces.

```bash theme={null}
friday workspace list
friday workspace list --json
```

**Aliases:** `friday workspace ls`, `friday w list`, `friday work list`

### friday workspace add

Register a space from a directory containing a `workspace.yml` file.

```bash theme={null}
friday workspace add -p /path/to/workspace
friday workspace add -p . --name my-space
friday workspace add --scan /projects --depth 2
```

| Flag                | Description                             |
| ------------------- | --------------------------------------- |
| `-p`                | Path to space directory (required)      |
| `--scan`            | Scan a directory recursively for spaces |
| `--depth`           | Maximum scan depth (default: 3)         |
| `--name, -n`        | Override space name                     |
| `--description, -d` | Add a description                       |

### friday workspace status

Show space configuration and details.

```bash theme={null}
friday workspace status -w my-space
```

| Flag | Description                 |
| ---- | --------------------------- |
| `-w` | Space ID or name (required) |

### friday workspace remove

Remove a space from the registry. Does **not** delete the directory.

```bash theme={null}
friday workspace remove -w my-space --yes
```

**Aliases:** `friday workspace rm`, `friday workspace delete`

| Flag    | Description                 |
| ------- | --------------------------- |
| `-w`    | Space ID or name (required) |
| `--yes` | Skip confirmation           |

### friday workspace cleanup

Remove spaces whose directories no longer exist on disk.

```bash theme={null}
friday workspace cleanup --yes
```

## Signals

### friday signal list

List configured signals for a space.

```bash theme={null}
friday signal list -w my-space
friday signal list -w my-space --json
```

**Alias:** `friday sig list`

| Flag | Description      |
| ---- | ---------------- |
| `-w` | Space ID or name |

### friday signal trigger

Trigger a signal manually.

```bash theme={null}
friday signal trigger -n my-signal -w my-space
friday signal trigger -n deploy --data '{"branch": "main"}'
friday signal trigger -n test --all
friday signal trigger -n my-signal -w my-space --stream
```

**Aliases:** `friday signal fire`, `friday signal send`

The `--data` flag takes a JSON payload directly — no `{"payload": ...}` envelope needed, the CLI adds it.

| Flag        | Description                                |
| ----------- | ------------------------------------------ |
| `-n`        | Signal name (required)                     |
| `--data`    | JSON payload                               |
| `-w`        | Target space                               |
| `--all`     | Trigger across all spaces                  |
| `--exclude` | Space IDs to skip (with `--all`)           |
| `--stream`  | Stream execution events in real time (SSE) |

## Sessions

### friday session list

List active and recent sessions.

```bash theme={null}
friday session list
friday session list --workspace my-space --json
```

**Aliases:** `friday ps`, `friday sesh list`

| Flag          | Description                |
| ------------- | -------------------------- |
| `--workspace` | Filter by space name or ID |
| `--json`      | Output as JSON             |

### friday session get

Get details for a specific session.

```bash theme={null}
friday session get sess_abc123
friday session get sess_abc123 --json
```

**Aliases:** `friday session show`, `friday session describe`

### friday session cancel

Cancel a running session.

```bash theme={null}
friday session cancel sess_abc123 --yes
```

**Aliases:** `friday session kill`, `friday session stop`

| Flag      | Description              |
| --------- | ------------------------ |
| `--force` | Force cancel             |
| `--yes`   | Skip confirmation prompt |

## Agents

See [built-in agents](/core-concepts/agents) for the full list of agents that ship with the platform.

### friday agent list

List available agents.

```bash theme={null}
friday agent list
friday agent list -w my-space --json
friday agent list --user
```

| Flag     | Description                                                     |
| -------- | --------------------------------------------------------------- |
| `-w`     | Filter by space                                                 |
| `--user` | List user-built agents from the Friday home `agents/` directory |
| `--json` | Output as JSON                                                  |

### friday agent describe

Show detailed information about an agent.

```bash theme={null}
friday agent describe -n slack
friday agent describe -n my-agent -w my-space
```

**Aliases:** `friday agent show`, `friday agent get`

| Flag | Description           |
| ---- | --------------------- |
| `-n` | Agent name (required) |
| `-w` | Space ID or name      |

### friday agent exec

Execute an agent via the Studio and stream results. Useful for testing agents in isolation before wiring them into a workflow.

```bash theme={null}
friday agent exec my-agent -i "Summarize the latest PRs"
friday agent exec my-agent -i "Check status" --json
friday agent exec my-agent -i "Deploy" --env "ENV=staging,TOKEN=xxx"
```

Requires the Studio to be running at `http://localhost:15200`.

**Alias:** `friday agent x`

| Flag      | Description                                      |
| --------- | ------------------------------------------------ |
| `<agent>` | Agent ID (positional, required)                  |
| `-i`      | Input prompt (required)                          |
| `--json`  | Output raw SSE events as NDJSON                  |
| `--url`   | Studio URL (default: `http://localhost:15200`)   |
| `--env`   | Environment variables as `KEY=VALUE,KEY2=VALUE2` |

## Skills

### friday skill list

List published skills.

```bash theme={null}
friday skill list
friday skill list --namespace tempest
friday skill list --query "code review"
```

| Flag          | Description             |
| ------------- | ----------------------- |
| `--namespace` | Filter by namespace     |
| `--query`     | Search query            |
| `--all`       | Include disabled skills |

### friday skill get

Get skill details.

```bash theme={null}
friday skill get -n @tempest/pr-code-review
```

| Flag | Description                                       |
| ---- | ------------------------------------------------- |
| `-n` | Skill name in `@namespace/name` format (required) |

### friday skill publish

Publish a skill from a directory containing a `SKILL.md` file.

```bash theme={null}
friday skill publish -p /path/to/skill
friday skill publish -p . --name @tempest/my-skill
```

**Alias:** `friday skill pub`

| Flag     | Description                                     |
| -------- | ----------------------------------------------- |
| `-p`     | Path to skill directory (default: `.`)          |
| `--name` | Override skill name from `SKILL.md` frontmatter |

### friday skill versions

List all versions of a skill.

```bash theme={null}
friday skill versions -n @tempest/pr-code-review
```

## Library

### friday library list

List stored artifacts and templates.

```bash theme={null}
friday library list
friday library list --tags csv,reports --limit 20
friday library list --since 2026-01-01
```

**Alias:** `friday library ls`

| Flag          | Description                      |
| ------------- | -------------------------------- |
| `--tags`      | Filter by tags (comma-separated) |
| `--since`     | Filter by date                   |
| `--limit`     | Max results (default: 50)        |
| `--workspace` | Filter by space path             |

### friday library get

Get a specific library item by ID (supports partial ID prefix).

```bash theme={null}
friday library get abc123
friday library get abc123 --content
```

| Flag        | Description                 |
| ----------- | --------------------------- |
| `--content` | Include item body in output |

## Artifacts

### friday artifacts list

List artifacts by space or chat.

```bash theme={null}
friday artifacts list --workspace my-space
friday artifacts list --chat chat_abc123 --limit 50
```

Must provide at least one of `--workspace` or `--chat`.

| Flag          | Description                |
| ------------- | -------------------------- |
| `--workspace` | Filter by space            |
| `--chat`      | Filter by chat             |
| `--limit`     | Max results (default: 100) |

### friday artifacts get

Get a specific artifact by ID.

```bash theme={null}
friday artifacts get art_abc123
friday artifacts get art_abc123 --revision 2
```

| Flag             | Description                         |
| ---------------- | ----------------------------------- |
| `--revision, -r` | Specific revision (default: latest) |

## Chat and prompts

### friday prompt

Send a prompt to the Friday conversation agent.

```bash theme={null}
friday prompt "Summarize last week's PRs"
friday prompt "Continue from earlier" --chat chat_abc123
friday prompt "Hello" --workspace my-space
```

**Alias:** `friday p`

Default output is NDJSON — the `cli-summary` line at the end carries the `chatId` for continuation.

| Flag              | Description                        |
| ----------------- | ---------------------------------- |
| `-w, --workspace` | Scope the chat to a specific space |
| `--chat`          | Continue an existing chat by ID    |
| `--human`         | Human-readable output              |

### friday chat

View chat transcripts. Without an ID, lists recent chats.

```bash theme={null}
friday chat
friday chat chat_abc123 --human
friday chat --limit 50
```

**Alias:** `friday ch`

| Flag             | Description                             |
| ---------------- | --------------------------------------- |
| `--human`        | Human-readable output                   |
| `--limit`        | Max chats to list (default: 25)         |
| `--show-prompts` | Include system prompt context in output |

## Logs

### friday logs

Query daemon logs with filtering.

```bash theme={null}
friday logs --since 5m --level error
friday logs --session sess_abc123 --human
friday logs --workspace my-space --since 1h
```

Reads logs from the Friday home directory (`global.log` and `workspaces/*.log`). Duration formats: `30s`, `5m`, `1h`. Level can be comma-separated (`error,warn`).

**Alias:** `friday log`

| Flag          | Description                                       |
| ------------- | ------------------------------------------------- |
| `--since`     | Time filter (e.g., `30s`, `5m`, `1h`)             |
| `--level`     | Filter by level: `debug`, `info`, `warn`, `error` |
| `--human`     | Human-readable output                             |
| `--chat`      | Filter by chat ID                                 |
| `--session`   | Filter by session ID                              |
| `--workspace` | Filter by space ID                                |

## Daemon

### friday daemon start

Start the Friday daemon.

```bash theme={null}
friday daemon start --detached
friday daemon start --detached --port 18080
```

**Alias:** `friday daemon run`

| Flag               | Description                                 |
| ------------------ | ------------------------------------------- |
| `--port`           | Port to listen on (default: 18080)          |
| `--hostname`       | Hostname to bind (default: `127.0.0.1`)     |
| `--detached`       | Run in background                           |
| `--max-workspaces` | Max concurrent space runtimes (default: 10) |
| `--idle-timeout`   | Idle timeout in seconds (default: 300)      |

### friday daemon stop

Stop the daemon gracefully.

```bash theme={null}
friday daemon stop
friday daemon stop --force
```

| Flag      | Description                          |
| --------- | ------------------------------------ |
| `--force` | Force stop even if spaces are active |

### friday daemon status

Check if the daemon is running.

```bash theme={null}
friday daemon status
friday daemon status --json
```

Exits 1 if the daemon is down — useful as a guard:

```bash theme={null}
friday daemon status || friday daemon start --detached
```

### friday daemon restart

Stop, wait 3 seconds, start detached.

```bash theme={null}
friday daemon restart
friday daemon restart --force
```

## Global options

Most commands support:

| Flag     | Description                                    |
| -------- | ---------------------------------------------- |
| `--json` | Output as JSON instead of human-readable text  |
| `--port` | Target a specific daemon port (default: 18080) |

## Version

```bash theme={null}
friday version
```

## Common patterns

```bash theme={null}
# Guard: start daemon if not running
friday daemon status || friday daemon start --detached

# Send a prompt and continue the conversation
CHAT_ID=$(friday prompt "hello" | jq -r 'select(.type=="cli-summary") | .chatId')
friday prompt --chat "$CHAT_ID" "follow up"

# Fire a signal and stream execution in real time
friday signal trigger -n my-signal -w my-space --data '{}' --stream

# Correlate logs with a session
friday logs --session sess_123 --human --since 5m

# Cancel the most recent active session
SID=$(friday session list --json | jq -r '[.[]|select(.status=="active")][0].id')
[ -n "$SID" ] && friday session cancel "$SID" --yes
```

## What the CLI can't do

Some operations require direct API calls — use `curl` against `http://localhost:18080`:

* Create a space from a parsed YAML config — `POST /api/workspaces/create`
* Partial space config updates — `PUT/PATCH /api/workspaces/:id/config/signals/:id`
* Resource upload or link — `POST /api/workspaces/:id/resources/upload`
* Memory reads — `GET /api/memory/:workspaceId/narrative/:memoryName`
* Env var management — `PUT /api/config/env`

See the [API reference](/api-reference/introduction) for the full endpoint list.