electric-sql / electric-sql/electric
electric-ax agents CLI reports "No entity types found" for freshly-registered types (default Electric-Principal has no visibility)
- Dominant language
- TypeScript
- Stars
- 10.4k
- Forks
- 375
- Avg merge
- 3d 1h
- Merged PRs (30d)
- 18
Description
## Summary
After following the agents walkthrough and registering an entity type, `electric-ax agents types` prints **`No entity types found`**, even though the type is registered and visible in the dev UI. The same mismatch affects other `agents` read commands. The cause is that the CLI sends a default `Electric-Principal` that the server has no visibility grants for.
## Steps to reproduce
1. Follow the agents walkthrough so an `assistant` (or any) entity type is registered against a local server at `http://localhost:4437`.
2. Confirm it registered — the dev UI at `https://localhost:4438` lists it, and:
```sh
curl -s http://localhost:4437/_electric/entity-types | jq '.[].name'
# => "assistant", "principal"
```
3. Run the CLI:
```sh
pnpx electric-ax@latest agents types
# => No entity types found
```
## Expected
Immediately after registering a type and following the walkthrough, `agents types` lists it.
## Actual
`No entity types found`, which reads as "registration failed" and sends you debugging the wrong thing.
## Root cause
`GET /_electric/entity-types` is scoped by the `Electric-Principal` request header:
- **No header** (plain `curl`) → returns everything (`assistant`, `principal`).
- **`Electric-Principal: system:dev-local`** (what the dev UI uses) → returns the registered types.
- **`Electric-Principal: user:@`** → returns `[]`.
`getElectricCliEnv` defaults the principal to `user:${ELECTRIC_AGENTS_IDENTITY}` where the identity is `${os.userInfo().username}@${os.hostname()}` (`packages/electric-ax`). That principal has no grants for the walkthrough-registered types, so the server correctly returns an empty list — and the CLI prints `No entity types found`.
Demonstration:
```sh
# empty (CLI default principal)
curl -s -H "Electric-Principal: user:$(whoami)@$(hostname)" \
http://localhost:4437/_electric/entity-types | jq length # => 0
# populated (dev UI principal)
curl -s -H "Electric-Principal: system:dev-local" \
http://localhost:4437/_electric/entity-types | jq 'map(.name)' # => ["assistant","principal"]
```
## Workaround
```sh
ELECTRIC_AGENTS_PRINCIPAL=system:dev-local electric-ax agents types
```
## Why this is confusing / suggested fixes
The inconsistency is that an unauthenticated request sees all types while the CLI's "authenticated" default sees none, and the walkthrough implies the plain `agents types` command lists what you just registered. Some options:
- Have the local dev flow default the CLI to the same principal the dev server/UI uses (`system:dev-local`), or grant the default `user:` principal visibility of types it can spawn.
- If empty-because-of-permissions is intended, distinguish it in the CLI output (e.g. `No entity types visible to principal
` with a hint about `ELECTRIC_AGENTS_PRINCIPAL`) instead of the flat `No entity types found`.
- At minimum, document the principal scoping in the walkthrough next to the `agents types` step.
## Environment
- `electric-ax` CLI `0.2.23` (and `@latest`), agents server image `0.6.3`, `@electric-ax/agents-runtime` `0.6.3`.
- macOS, local Docker dev stack (`electric-ax agents start`).
Contributor guide
Research direction
Start in packages/electric-ax at getElectricCliEnv and trace how the agents read commands, including agents types, construct their principal headers. Reproduce the empty and populated responses with the two Electric-Principal values shown in the issue, then choose and implement the intended local behavior or clearer permission-aware output. Done means a freshly registered type is discoverable through the walkthrough command, or the CLI clearly explains why it is not visible.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- authorization, cli
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100