Skip to content

feat(api): add v2 resource management endpoints #6900

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TheodoreSpeaks merged 4 commits into from
Aug 20, 2026
Merged

feat(api): add v2 resource management endpoints #6900

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5f01d47
feat(api): add v2 resource management endpoints
TheodoreSpeaks Aug 20, 2026
a3ae61e
fix(cli): gate destructive v2 commands
TheodoreSpeaks Aug 20, 2026
45006ab
fix(test): update v2 request-slice count
TheodoreSpeaks Aug 20, 2026
f0b8e0b
feat(cli): add shared workspace profiles
TheodoreSpeaks Aug 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 32 additions & 2 deletions apps/docs/content/docs/en/cli/authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,20 @@ sim workflows list --workspace ws_other
`sim login --workspace <id>` preselects a workspace in the picker, and
re-logging into an existing profile preselects the one already configured.

To save another workspace without minting or copying another personal key, add
a workspace profile:

```bash
sim workspaces list
sim profile add acme --workspace ws_acme
sim --profile acme whoami
```

The new profile stores `auth_profile = default` and its own workspace. Omit
`--workspace` in an interactive terminal to choose from the workspaces the
active key can access; scripts must provide the workspace ID explicitly. The
picker is capped at 1,000 entries and asks for an explicit ID above that.

## Checking who you are

```bash
Expand All @@ -76,6 +90,12 @@ sim logout # remove the stored key
sim logout --all # remove the profile entirely, including its settings
```

A workspace profile that shares authentication cannot remove the shared key.
Remove only that local profile with `sim logout --all --profile <name>`, or log
out of the authentication profile named by the error message. Removing an
authentication profile entirely is refused until its workspace profiles are
removed, so it cannot leave dangling references.

<Callout type="warn">
`sim logout` removes the key from disk but does **not** revoke it. Revoke keys in
Sim under **Settings → API keys**.
Expand Down Expand Up @@ -116,9 +136,9 @@ jobs:
SIM_WORKSPACE: ${{ vars.SIM_WORKSPACE }}
```

## Several accounts at once
## Several accounts and workspaces

Each profile holds one identity and one set of defaults:
Use separate logins for separate identities or deployments:

```bash
sim login --profile dev --endpoint http://localhost:3000
Expand All @@ -128,6 +148,16 @@ sim workflows list --profile dev
sim workflows list --profile prod
```

Use workspace profiles when one personal key should target several workspaces:

```bash
sim profile add marketing --workspace ws_marketing
sim profile add support --workspace ws_support

sim workflows list --profile marketing
sim workflows list --profile support
```

See [Configuration](/cli/configuration) for how profiles are stored and resolved.

## Self-hosted and non-production deployments
Expand Down
9 changes: 1 addition & 8 deletions apps/docs/content/docs/en/cli/commands.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ These apply to every command, and may be written before or after it.

| Group | Description |
| --- | --- |
| [`sim profiles`](/cli/profiles) | List profiles or add a workspace profile that shares a stored login |
| [`sim audit-logs`](/cli/audit-logs) | Manage audit logs |
| [`sim billing`](/cli/billing) | Manage billing |
| [`sim credentials`](/cli/credentials) | Manage credentials |
Expand Down Expand Up @@ -94,14 +95,6 @@ sim whoami [options]

</CommandTable>

## List the profiles defined in the config and credentials files

```bash
sim profiles
```

Also available as `sim profile`.

## Set a profile's endpoint, default workspace, or output format

```bash
Expand Down
35 changes: 32 additions & 3 deletions apps/docs/content/docs/en/cli/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,10 @@ for a single command.

## Profiles

A profile is one identity plus one set of defaults, in the style of the AWS CLI.
Select one with `-P`, `--profile`, or `SIM_PROFILE`:
A profile selects one set of defaults, in the style of the AWS CLI. It normally
uses its same-named stored identity, but a workspace profile can share another
profile's identity through `auth_profile`. Select one with `-P`, `--profile`, or
`SIM_PROFILE`:

```bash
sim workflows list --profile dev
Expand All @@ -23,6 +25,12 @@ The profile is named `default` when you do not pick one.
sim profiles # list them; * marks the active one
```

Add a profile for another workspace without creating or copying an API key:

```bash
sim profile add acme --workspace ws_acme
```

## Setting defaults

```bash
Expand Down Expand Up @@ -51,7 +59,7 @@ Each setting resolves independently, and the first match wins:
| --- | --- |
| 1 | Command-line flag — `--endpoint`, `--workspace`, `--output` |
| 2 | Environment — `SIM_ENDPOINT`, `SIM_API_KEY`, `SIM_WORKSPACE`, `SIM_OUTPUT` |
| 3 | `~/.sim/config` and `~/.sim/credentials`, for the selected profile |
| 3 | `~/.sim/config` for the selected profile and `~/.sim/credentials` for its `auth_profile`, when set |
| 4 | Built-in default — `https://www.sim.ai` and `table` |

`sim whoami` prints the winning source for each setting:
Expand All @@ -74,6 +82,10 @@ output = table
[profile dev]
endpoint = http://localhost:3000
workspace = ws_local

[profile acme]
auth_profile = default
workspace = ws_acme
```

Keys live in `~/.sim/credentials`, written `0600`:
Expand All @@ -89,6 +101,10 @@ api_key = sim_…
Section naming follows the AWS convention: `[profile dev]` in config, `[dev]` in
credentials. The `default` profile is `[default]` in both.

`auth_profile` references one direct profile and shares only its endpoint and
API key; workspace and output remain local. References cannot be chained, and a
shared profile cannot also set its own endpoint or API key.

## Environment variables

| Variable | Effect |
Expand Down Expand Up @@ -121,6 +137,19 @@ sim configure --set-workspace ws_abc123
export SIM_WORKSPACE=ws_abc123
```

For a reusable selection, create a workspace profile backed by the current
stored login:

```bash
sim workspaces list
sim profile add acme --workspace ws_acme
sim --profile acme tables list
```

When `--workspace` is omitted in a terminal, `profile add` presents an
interactive picker, capped at 1,000 entries. It refuses environment-only keys
and endpoint overrides because those values would disappear in another shell.

`sim billing status`, `sim billing logs`, and `sim audit-logs list` accept
`--all-workspaces` to drop the filter instead. It cannot be combined with
`--workspace`.
Expand Down
218 changes: 218 additions & 0 deletions apps/docs/content/docs/en/cli/knowledge.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -213,6 +213,196 @@ sim knowledge create [options]

</CommandTable>

## Create knowledge connector

```bash
sim knowledge connectors create <id> [options]
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Unique knowledge base identifier. |

</CommandTable>

**Options**

<CommandTable>

| Option | Required | Description |
| --- | --- | --- |
| `--connector-type <value>` | Yes | Registered connector type. |
| `--credential-id <value>` | No | OAuth credential identifier for connectors that require OAuth. |
| `--api-key <value>` | No | Write-only API key for connectors that use API-key authentication. |
| `--source-config <json\|@file>` | Yes | Connector-specific source selection and filtering configuration. (JSON, or @path / @- to read a file or stdin). |
| `--sync-interval-minutes <value>` | No | Scheduled synchronization interval in minutes; zero disables scheduling. |

</CommandTable>

## Delete knowledge connector

```bash
sim knowledge connectors delete <id> <connectorId> [options]
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Knowledge base that owns the connector. |
| `connectorId` | Yes | Connector selected for the operation. |

</CommandTable>

**Options**

<CommandTable>

| Option | Required | Description |
| --- | --- | --- |
| `--delete-documents` | No | Also permanently delete documents produced by this connector. |
| `--no-delete-documents` | No | Send --delete-documents as false. |
| `-y, --yes` | Yes | Confirm this destructive operation. |

</CommandTable>

## Get knowledge connector

```bash
sim knowledge connectors get <id> <connectorId>
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Knowledge base that owns the connector. |
| `connectorId` | Yes | Connector selected for the operation. |

</CommandTable>

## List knowledge connector documents

```bash
sim knowledge connectors documents list <id> <connectorId> [options]
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Knowledge base that owns the connector. |
| `connectorId` | Yes | Connector selected for the operation. |

</CommandTable>

**Options**

<CommandTable>

| Option | Required | Description |
| --- | --- | --- |
| `--include-excluded` | No | Include documents explicitly excluded by a user. |
| `--no-include-excluded` | No | Send --include-excluded as false. |
| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |

</CommandTable>

## List knowledge connectors

```bash
sim knowledge connectors list <id> [options]
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Unique knowledge base identifier. |

</CommandTable>

**Options**

<CommandTable>

| Option | Required | Description |
| --- | --- | --- |
| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `connectorType`, `createdAt`, `updatedAt`. |
| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |

</CommandTable>

## Update knowledge connector

```bash
sim knowledge connectors update <id> <connectorId> [options]
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Knowledge base that owns the connector. |
| `connectorId` | Yes | Connector selected for the operation. |

</CommandTable>

**Options**

<CommandTable>

| Option | Required | Description |
| --- | --- | --- |
| `--source-config <json\|@file>` | No | Replacement source selection and filtering configuration. (JSON, or @path / @- to read a file or stdin). |
| `--sync-interval-minutes <value>` | No | New scheduled synchronization interval in minutes. |
| `--status <value>` | No | New connector state. Accepted values: `active`, `paused`. |

</CommandTable>

## Update knowledge connector documents

```bash
sim knowledge connectors documents update <id> <connectorId> [options]
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Knowledge base that owns the connector. |
| `connectorId` | Yes | Connector selected for the operation. |

</CommandTable>

**Options**

<CommandTable>

| Option | Required | Description |
| --- | --- | --- |
| `--operation <value>` | Yes | Whether to restore or exclude the selected documents. Accepted values: `restore`, `exclude`. |
| `--document <value...>` | Yes | Connector document identifiers to update. (space-separated, or @path / @- with one value per line). |

</CommandTable>

## Create a knowledge folder at a path

```bash
Expand Down Expand Up @@ -398,6 +588,34 @@ sim knowledge search [options]

</CommandTable>

## Sync knowledge connector

```bash
sim knowledge sync create <id> <connectorId> [options]
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Knowledge base that owns the connector. |
| `connectorId` | Yes | Connector selected for the operation. |

</CommandTable>

**Options**

<CommandTable>

| Option | Required | Description |
| --- | --- | --- |
| `--rehydrate` | No | Re-fetch and re-index every existing connector document. |
| `--no-rehydrate` | No | Send --rehydrate as false. |

</CommandTable>

## Update knowledge base

```bash
Expand Down
Loading
Loading