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

# Projects and channels

> Create and manage projects (AI assistants), upload knowledge files, connect channels (Web, WhatsApp, Facebook, Instagram), and sync a project's workflows between your machine and the server.

A **project** is an AI assistant with its knowledge files, its
channels, and its workflows. The `jelou project` subcommand manages the project
lifecycle; `jelou channels` connects the project to messaging
channels; and the sync commands (`link`, `pull`, `status`, `push`,
`incoming`) bring the project's workflows down to local files and back.

<Note>
  "Brain" is the legacy name for "project". `--brain` is accepted as an alias of
  `--project` in `jelou link` and `jelou channels`, and several API-level
  fields keep the `brain` name — but the canonical name is **project**.
</Note>

## `jelou project`

| Subcommand                        | Description                                              |
| --------------------------------- | -------------------------------------------------------- |
| `list`                            | Lists all projects (paginated)                           |
| `show <id>`                       | Shows project details and file count                     |
| `create "<name>"`                 | Creates a new project                                    |
| `update <id>`                     | Updates name or description                              |
| `delete <id>`                     | Deletes a project (cascading, irreversible)              |
| `publish <id>`                    | Publishes the draft to a production branch               |
| `history <id>`                    | Project version / commit history                         |
| `restore <id> <commit>`           | Restores to a previous commit or loads it into the draft |
| `knowledge list <id>`             | Lists the knowledge files                                |
| `knowledge upload <id> <file>`    | Uploads a knowledge file                                 |
| `knowledge delete <id> <file-id>` | Deletes a knowledge file                                 |

```bash theme={null}
jelou project list --page 2 --limit 5 --json
jelou project show 01H2XCEJQTG2H5V5NKCYW3J7Z2
jelou project create "Product Support" --description "Customer support AI"
jelou project update 01H2XCEJQTG2H5V5NKCYW3J7Z2 --name "Support v2"
jelou project delete 01H2XCEJQTG2H5V5NKCYW3J7Z2 --yes
```

### Knowledge

Upload documents for the assistant to use as a knowledge base.
Supported formats: PDF, TXT, CSV (max. 2 MB per file).

```bash theme={null}
jelou project knowledge upload 01H2XCEJQTG2H5V5NKCYW3J7Z2 ./catalog.pdf
jelou project knowledge upload 01H2XCEJQTG2H5V5NKCYW3J7Z2 ./faq.txt --name "FAQ"
jelou project knowledge list 01H2XCEJQTG2H5V5NKCYW3J7Z2
jelou project knowledge delete 01H2XCEJQTG2H5V5NKCYW3J7Z2 file_01H2XCEJQ --yes
```

### Publish and restore

```bash theme={null}
jelou project publish 01H2XCEJQTG2H5V5NKCYW3J7Z2 --branch master --commit-name "Release v2" --yes
jelou project history 01H2XCEJQTG2H5V5NKCYW3J7Z2 --detailed --limit 50
jelou project restore 01H2XCEJQTG2H5V5NKCYW3J7Z2 abc123def456 --into-draft --yes
```

<Warning>
  `project delete` is **cascading and irreversible**: it deletes the project, its
  workspace, its default skill, and its sandbox channel. `publish` and `restore`
  affect production immediately, and deleting a knowledge file triggers a
  re-training (responses may change). Run `project show` and
  confirm before destructive operations.
</Warning>

## `jelou channels`

Connect a project to messaging channels.

| Subcommand                                              | Description                                                                             |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `list --project <id>`                                   | Lists a project's channels (filter with `--type`)                                       |
| `show <id>`                                             | Shows the full detail for one channel, including Meta's `pageId` for Facebook/Instagram |
| `activate whatsapp`                                     | Connects a WhatsApp number through Meta's sign-in flow (no credentials to paste)        |
| `create --project <id> --type web --name "<n>"`         | Creates a channel (CLI-only supports `--type web`)                                      |
| `connect <channel-id> --to <bot\|agent\|pma> --id <id>` | Routes the channel to a bot, agent, or PMA                                              |
| `flows --bot-id <id>`                                   | Lists the WhatsApp Flows available for a bot                                            |
| `testers`                                               | Manages the WhatsApp sandbox tester phone whitelist                                     |

CLI-only, `channels create` supports `--type web` (web widget). WhatsApp,
Facebook, and Instagram channels require OAuth: WhatsApp is connected with
`jelou channels activate` (Meta's sign-in flow, no credentials to paste),
while Facebook and Instagram can only be created from the dashboard.

```bash theme={null}
jelou channels list --project 01H2XCEJQTG2H5V5NKCYW3J7Z2 --exclude-sandbox
jelou channels list --type Facebook_Feed          # the page's comments inbox, not Messenger
jelou channels create --project 01H2XCEJQTG2H5V5NKCYW3J7Z2 --type web --name "Site Widget"
jelou channels activate whatsapp --project 01H2XCEJQTG2H5V5NKCYW3J7Z2
jelou channels connect 01H2XCEJQTG2H5V5NKCYW3J7Z2 --to bot --id bot_01H2XCEJQ
```

<Note>
  `--type` is exact: `Facebook` means Messenger DMs only, `Facebook_Feed` is the
  page's comments inbox (previously invisible to the CLI); same pattern for
  `Instagram`/`Instagram_Feed`. Connecting a Facebook page is only half the
  job — each skill needs its own Facebook channel entry, added in Studio, or
  the engine finds no workflow for that traffic and nothing replies.
</Note>

<Warning>
  `channels connect` **overwrites without warning**: if the channel already had a
  connection, re-pointing it routes real users to the new destination on the next
  incoming message. Verify both destinations before connecting.
</Warning>

## Sync workflows (local ↔ server)

To edit a project's workflows as local files, first link
the directory to the project with `jelou link`, then pull (`pull`), review
(`status`), edit, and push (`push`).

### `jelou link`

```bash theme={null}
jelou link                                   # interactive
jelou link --project 01H2XCEJQTG2H5V5NKCYW3J7Z2
jelou link --project 01H2XCEJQTG2H5V5NKCYW3J7Z2 --authoring ts   # pins the authoring mode (ts|json) in jelou.yml
jelou link --status --json                   # shows the link without calling the API
```

It writes `jelou.yml` (team-shared link — version it in git) and
`.jelou/state.json` (local state — add it to `.gitignore`; the CLI does it
automatically).

<Warning>
  `jelou link`, `pull`, and `push` write local files. They require a clean git
  worktree or an empty directory. If the directory is dirty or not versioned,
  the CLI stops; use `--allow-dirty` only after confirming.
</Warning>

### `pull`, `status`, `push`

```bash theme={null}
jelou pull                       # pulls all workflows to workflows/<slug>.<channel>.json
jelou pull --check --json        # dry-run: summary without writing
jelou pull --workflow saludo     # a single workflow
jelou pull --quiet --json        # no informational stderr chatter (agent use)

jelou status                     # diff local vs lockfile
jelou status --check-remote      # also compares against the server (detects drift)
jelou status --quiet --json      # only shows non-clean entries (CI-friendly)

jelou push                       # pushes the local edits
jelou push --dry-run --json      # only shows the diff, doesn't dispatch
jelou push --workflow saludo     # a single workflow
jelou push --force               # skips the lockfile drift check (Layer 1)
jelou push --repair-from .jelou/journals/2026-05-03T20-45-52-000Z.json   # replays an incomplete or failed journal
```

<Tip>
  Need the full picture, not just sync status? `jelou context --agent` returns
  the same drift information as `status` in a single call, plus identity, the
  AI model allowlist, secret names, database inventory, and the node-type
  catalog — replacing the `status` + `secret list` + `models list` +
  `databases list` + `workflow node-spec --list` sequence for agents that want
  the whole startup context at once.
</Tip>

### `jelou incoming` — resolving concurrent edits

If a `pull` detects that the server changed a workflow that you also edited
locally, it preserves the server version under `.jelou/incoming/` and exits with
code 7. Resolve each artifact before running `pull` again:

```bash theme={null}
jelou incoming list
jelou incoming diff --workflow wf_01H2XCEJQ
jelou incoming accept-server --workflow wf_01H2XCEJQ --channel default   # adopt the server
jelou incoming accept-local  --workflow wf_01H2XCEJQ --channel default   # push the local one (force-with-lease)
jelou incoming mark-resolved --workflow wf_01H2XCEJQ                      # clear without applying either
```

<Note>
  `accept-local` performs a CAS check against the recorded server hash:
  if the server diverged since the artifact was captured, it refuses with
  `NEW_REMOTE_DRIFT`. Run `mark-resolved` and then `pull` to see the new
  divergence.
</Note>