electric-sql / electric-sql/electric

electric-ax agents CLI reports "No entity types found" for freshly-registered types (default Electric-Principal has no visibility)

Open
#4,719 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.