---
# @generated by sylphx-gen 0.1.0 from contracts@fb95f0c42a0ec5d8e3cb694c0054b529c0b24b184112c65ef60c9044b4ce61f9. Do not edit.
title: "sylphx knowledge entities"
description: "The sylphx knowledge entities commands of Sylphx Knowledge: every verb, with its argument, its flags and a run line."
type: reference
product: knowledge
summary: "Every sylphx knowledge entities command: its argument, its flags and a run line."
updated: 2026-09-28
nav: false
---

The `entities` commands of Sylphx Knowledge, as the CLI spells them: the same
calls as [the `entities` API page](/docs/api/entities), typed for the
shell. [Install, sign in and the grammar](/docs/cli) are on the CLI index.

**Not available yet.** Sylphx Knowledge is declared in the registry but no backend serves it: every command answers `501` with the problem code `UNIMPLEMENTED`.

## get

Gets an entity.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx knowledge entities get orgs/acme/projects/shop/envs/production/entities/entity
```

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/entities/entity` · scope `knowledge:read` · effect `read` · [Request, response and examples](/docs/api/entities/get)

## list

Lists the entities the caller may see. The filter is limited to `entity_type` and `lifecycle`.

**`PARENT`** — optional: the CLI fills it from the linked project or the
key's scope when it is left out.

**CLI**

```bash
sylphx knowledge entities list orgs/acme/projects/shop/envs/production
```

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/entities` · scope `knowledge:read` · effect `read` · [Request, response and examples](/docs/api/entities/list)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--page-size` | `int` | At most this many; default 50, clamped to 1000. |
| `--page-token` | `string` | `next_page_token` of the previous page. |
| `--filter` | `string` | AIP-160 filter, limited to `entity_type` and `lifecycle`. |

## create

Creates an entity in a space. An entity whose external id already names one in the graph is refused with `RESOURCE_ALREADY_EXISTS`, which names it; use Update with `allow_missing` to upsert.

**`ID`** — The id segment of the new Resource's name; the server assigns one when omitted.

**CLI**

```bash
sylphx knowledge entities create --parent orgs/acme/projects/shop/envs/production --entity-type … --title … --space …
```

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/entities` · scope `knowledge:write` · effect `write` · [Request, response and examples](/docs/api/entities/create)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--parent` | `string` | The parent to create in; defaults to the linked project or the key's scope. |
| `--meta.labels` | `key=value` | Caller-writable, indexed labels (AIP-122 label rules). Repeat the flag for each value. |
| `--meta.annotations` | `key=value` | Caller-writable, unindexed annotations. Repeat the flag for each value. |
| `--meta.display-name` | `string` | Caller-writable human-readable name. |
| `--entity-type` | `string` | The type: a core type (`person`, `organisation`, `customer`, `contact`, `product`, `project`, `document`, `decision`, `playbook`, `case`, `topic`) or a type of an accepted Knowledge Schema, `<schema>.<type>`. Required. |
| `--title` | `string` | The name people use for it. Required. |
| `--aliases` | `string` | Other names it is known by; at most 50. Repeat the flag for each value. |
| `--properties` | `json` | Properties, valid against the type's JSON Schema. |
| `--external-ids` | `json` | Identifiers in other systems. Two writes with the same external id in one graph are the same entity (deterministic resolution). At most 50. Repeat the flag for each value. |
| `--space` | `string` | The space the entity was first stated in. Required. |
| `--dry-run` | `bool` | Validate and print the result without writing (validate_only). |

## update

Updates an entity. With `allow_missing` it is the structured upsert (`upsert_entity`): an entity matched by `external_ids` is updated, otherwise one is created.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx knowledge entities update orgs/acme/projects/shop/envs/production/entities/entity --entity-type … --title …
```

`PATCH https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/entities/entity` · scope `knowledge:write` · effect `write` · [Request, response and examples](/docs/api/entities/update)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--meta.labels` | `key=value` | Caller-writable, indexed labels (AIP-122 label rules). Repeat the flag for each value. |
| `--meta.annotations` | `key=value` | Caller-writable, unindexed annotations. Repeat the flag for each value. |
| `--meta.display-name` | `string` | Caller-writable human-readable name. |
| `--entity-type` | `string` | The type: a core type (`person`, `organisation`, `customer`, `contact`, `product`, `project`, `document`, `decision`, `playbook`, `case`, `topic`) or a type of an accepted Knowledge Schema, `<schema>.<type>`. Required. |
| `--title` | `string` | The name people use for it. Required. |
| `--aliases` | `string` | Other names it is known by; at most 50. Repeat the flag for each value. |
| `--properties` | `json` | Properties, valid against the type's JSON Schema. |
| `--external-ids` | `json` | Identifiers in other systems. Two writes with the same external id in one graph are the same entity (deterministic resolution). At most 50. Repeat the flag for each value. |
| `--allow-missing` | `bool` | Create the entity when no entity matches (`upsert_entity`): the name, or else `external_ids`, identifies it. |
| `--dry-run` | `bool` | Validate and print the result without writing (validate_only). |

## delete

Deletes an entity and every fact about it. With `force` it is a data-rights erasure: the episodes the person wrote are deleted too, with their search and embedding entries.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx knowledge entities delete orgs/acme/projects/shop/envs/production/entities/entity --yes
```

`DELETE https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/entities/entity` · scope `knowledge:write` · effect `destructive` · [Request, response and examples](/docs/api/entities/delete)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--etag` | `string` | Delete only if the current etag matches. |
| `--allow-missing` | `bool` | Succeed when the entity does not exist. |
| `--dry-run` | `bool` | Validate and print the result without writing (validate_only). |
| `--force` | `bool` | Also delete the episodes this person wrote (a data-rights erasure). |
| `--yes` | `bool` | Do not ask before this destructive call. |

## merge

Merges other entities into this one: their facts and external ids resolve to it. The merge is recorded and reversible with `:split`; it is never a silent rewrite.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx knowledge entities merge orgs/acme/projects/shop/envs/production/entities/entity
```

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/entities/entity:merge` · scope `knowledge:write` · effect `write` · [Request, response and examples](/docs/api/entities/merge)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--entities` | `string` | The entities to merge into it; 1 to 20. Required. Repeat the flag for each value. |
| `--reason` | `string` | Why they are the same, recorded with the merge; at most 1000 characters. |

## split

Splits a merged entity back out of this one, with the facts and external ids it brought.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx knowledge entities split orgs/acme/projects/shop/envs/production/entities/entity
```

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/entities/entity:split` · scope `knowledge:write` · effect `write` · [Request, response and examples](/docs/api/entities/split)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--entity` | `string` | The merged entity to restore. Required. |

## profile

Returns one entity's profile in one call (`entity`): the entity, its current facts in both directions, the entities they name and the recent episodes about it, trimmed to what the caller may see. A read with a request body.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx knowledge entities profile orgs/acme/projects/shop/envs/production/entities/entity
```

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/entities/entity:profile` · scope `knowledge:read` · effect `read` · [Request, response and examples](/docs/api/entities/profile)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--valid-time` | `timestamp` | The profile as it was valid at this time; default now. |
| `--max-episodes` | `int` | At most this many recent episodes; default 20, clamped to 100. |

## recall

Searches the graph (`recall`): hybrid lexical and semantic search over episodes and facts, fused by reciprocal rank, then at most two hops of expansion from the top entities. Returns a context pack with citations, built only from records the caller may see.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx knowledge entities recall orgs/acme/projects/shop/envs/production
```

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/entities:recall` · scope `knowledge:read` · effect `read` · [Request, response and examples](/docs/api/entities/recall)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--query` | `string` | What to recall, in natural language; 1 to 4000 characters. Required. |
| `--spaces` | `string` | The spaces to search, as resource names; default every space the caller may read. At most 50. Repeat the flag for each value. |
| `--entity-types` | `string` | Only entities of these types; default every type. Repeat the flag for each value. |
| `--valid-time` | `timestamp` | Recall the graph as it was valid at this time; default now. |
| `--max-hops` | `int` | How many hops to expand from the top entities, 0 to 2; default 2. |
| `--max-facts` | `int` | At most this many facts in the pack; default 30, clamped to 200. |

## ask

Answers a question through Sylphx AI (`ask`), from a context pack built only from records the caller may see, with citations to its episodes.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx knowledge entities ask orgs/acme/projects/shop/envs/production
```

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/entities:ask` · scope `knowledge:read` · effect `read` · [Request, response and examples](/docs/api/entities/ask)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--question` | `string` | The question, in natural language; 1 to 4000 characters. Required. |
| `--spaces` | `string` | The spaces to answer from, as resource names; default every space the caller may read. At most 50. Repeat the flag for each value. |
| `--valid-time` | `timestamp` | Answer about the graph as it was valid at this time; default now. |