electric-ax agents CLI reports "No entity types found" for freshly-registered types (default Electric-Principal has no visibility)
Nobody has claimed this yet.
Assessment
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Newbie friendliness
- 55/100
- Issue type
- Bug
- Clarity
- Mostly clear
- Activity status
- Quiet
- Tech stack
- typescript
- Domain
- authorization, cli
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.
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
- Follow the agents walkthrough so an
assistant(or any) entity type is registered against a local server athttp://localhost:4437. - Confirm it registered — the dev UI at
https://localhost:4438lists it, and:curl -s http://localhost:4437/_electric/entity-types | jq '.[].name' # => "assistant", "principal" - Run the CLI:
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:<whoami>@<hostname>→ 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:
# 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
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 defaultuser:<identity>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 <p>with a hint aboutELECTRIC_AGENTS_PRINCIPAL) instead of the flatNo entity types found. - At minimum, document the principal scoping in the walkthrough next to the
agents typesstep.
Environment
electric-axCLI0.2.23(and@latest), agents server image0.6.3,@electric-ax/agents-runtime0.6.3.- macOS, local Docker dev stack (
electric-ax agents start).
- Dominant language
- TypeScript
- Stars
- 10.4k
- Forks
- 399
- PR merge metrics
- No merged PRs in 30d
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from electric-sql/electric
-
camelToSnake and snakeCamelMapper() drop the underscore when a digit precedes a camelCase boundaryOpen
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
electric-sql/electric#4855 ·
-
ShapeStream does not notify subscribers when it gives up on a non-Error valuePossibly taken @Tyagiquamar claimed this 19 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
electric-sql/electric#4830 ·
-
@electric-sql/client throws SecurityError on import when the browser blocks site storage (typeof localStorage outside try)Possibly taken @mohanedmoh claimed this 37 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
electric-sql/electric#4826 · 1 comment ·
-
agents-chat-starter: spawn PUT goes to the durable-streams proxy, so no entity is created and agents never wakePossibly taken @adityavkk claimed this 133 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
electric-sql/electric#4687 ·
-
Listen IP addressOpenfeature request triage
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
electric-sql/electric#4150 · 1 comment ·
All issues in electric-sql/electric
Similar issues
-
area:cli area:security bug priority:medium
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
Maintainers usually reply within 1 day
-
"code source" and "numerique.gouv" links: "new window" mention duplicated in the accessible nameOpenaccessibility
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
numerique-gouv/lasuite-landingpage#315 ·
Maintainers usually reply within 1 day
-
needs:triage
Difficulty 1/5 Under an hour Newbie friendliness 92/100
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 72/100
HyeokjaeChoi/vaultme#585 ·
Maintainers usually reply within 1 day
-
enhancement priority/P2
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
beettlle/pi-smart-router#200 ·