From 5d5e1058260a6fd8c3f2675372e5cdb40240a8ea Mon Sep 17 00:00:00 2001 From: Theodore Li Date: Wed, 26 Aug 2026 13:01:00 -0700 Subject: [PATCH] improvement(cli): clarify npm package readmes --- packages/sim-cli/README.md | 521 +++++++++++++---------------------- packages/sim-setup/README.md | 267 +++++++++++++++++- 2 files changed, 445 insertions(+), 343 deletions(-) diff --git a/packages/sim-cli/README.md b/packages/sim-cli/README.md index 50104aec348..fd86dc9ca79 100644 --- a/packages/sim-cli/README.md +++ b/packages/sim-cli/README.md @@ -1,426 +1,273 @@ # Sim CLI -Talk to the [Sim](https://sim.ai) API from your terminal. +`sim` is the command-line client for [Sim](https://sim.ai), a workspace for +building, deploying, and managing AI agents and workflows. -```bash -npm install -g sim -sim login -sim workflows list -``` - -Full documentation: **https://docs.sim.ai/cli** - -## Profiles +Use the CLI to work with an existing Sim account or self-hosted deployment from +your terminal. You can run workflows, inspect logs, query tables, manage files +and knowledge bases, and configure workspace resources. The CLI does not install +or run Sim itself; see the +[self-hosting guide](https://docs.sim.ai/platform/self-hosting/docker) if you need +to set up a Sim deployment. -Profiles work like the AWS CLI and are selected with `-P`, `--profile`, or -`SIM_PROFILE`. A profile normally owns one identity and one set of defaults; a -workspace profile can instead share a stored identity through `auth_profile`. +## Install -Non-secret settings live in `~/.sim/config`: +The CLI requires Node.js 20 or newer. -```ini -[default] -endpoint = https://www.sim.ai -workspace = b7f4a1c3-9e02-4d68-8a5b-1c3f6d90e274 -output = table - -[profile dev] -endpoint = http://localhost:3000 -workspace = a3c81b02-5f4d-4e19-9d7a-2b6c1e084f55 - -[profile acme] -auth_profile = default -workspace = 7e2d9c14-6b83-4a55-8f01-c4d3e9a76b28 -``` - -Keys live in `~/.sim/credentials`, written `0600`: - -```ini -[default] -api_key = sim_… - -[dev] -api_key = sim_… +```bash +npm install --global sim +sim --version ``` -The section-naming asymmetry — `[profile dev]` in config, `[dev]` in credentials -— is the AWS convention, kept so existing habits and tooling carry over. +You can also run a command without installing the package globally: ```bash -sim configure --set-endpoint http://localhost:3000 --profile dev -sim configure --set-workspace a3c81b02-5f4d-4e19-9d7a-2b6c1e084f55 --profile dev - -sim profiles # list them; * marks the active one -sim whoami # resolved values, where each came from, and whether they work - -# Share the active stored login with a second workspace -sim profile add acme --workspace 7e2d9c14-6b83-4a55-8f01-c4d3e9a76b28 +npx sim --help ``` -A profile name that is not configured is refused, with the closest configured -name suggested. A typo used to fall through to the built-in defaults, so -`--profile stagng` talked to production and handed it whatever key resolved. -The two exceptions are the commands whose job is to create a profile: -`sim login --profile new` and `sim configure --profile new` still accept a name -that does not exist yet. +## Get started -## Where settings come from +Sign in to the default profile: -Each setting resolves independently, first match wins: - -| Rank | Source | -| --- | --- | -| 1 | Command-line flag (`--endpoint`, `--workspace`, `--output`) | -| 2 | Environment (`SIM_ENDPOINT`, `SIM_API_KEY`, `SIM_WORKSPACE`, `SIM_OUTPUT`) | -| 3 | `~/.sim/config` for the selected profile and credentials for its `auth_profile`, when set | -| 4 | Built-in default (`https://www.sim.ai`, `table`) | - -`SIM_TIMEOUT_SECONDS` bounds each request (default `3600`, `0` waits -indefinitely) and `SIM_DEBUG=1` traces requests to stderr. Node ignores -`HTTPS_PROXY` unless `NODE_USE_ENV_PROXY=1` is also set, on Node 22.21+ or -24.5+; the CLI warns when a proxy is configured but will not be used. - -Formats are listed under [Output formats](#output-formats). +```bash +sim login +``` -`sim whoami` prints the winning source per setting, which is usually the fastest -way to explain a surprising result. It then reads the configured workspace to -prove the settings actually work; `--no-verify` skips that and stays offline. +The CLI opens a browser and prints a pairing code. Confirm that the code in the +browser matches the one in your terminal, approve the login, and choose a +workspace. The selected workspace becomes the default for this profile. -Its exit status is the answer, so CI can branch on it: +The login stores a personal API key locally. It does not start a local callback +server, so the same flow works over SSH and in containers. Use +`sim login --no-browser` when the browser is on another machine. -| Code | Meaning | -| --- | --- | -| `0` | The key works and reached the configured workspace | -| `1` | The credentials are wrong — no key stored, or the API refused it | -| `2` | The check could not be made — nothing to check against, or the endpoint did not answer | +Check the active profile and verify that its endpoint, API key, and workspace +work together: -For CI, skip `sim login` entirely and set `SIM_API_KEY` and `SIM_WORKSPACE` — -nothing needs to touch the filesystem. `SIM_CONFIG_DIR` relocates both files if -you need to keep them somewhere other than `~/.sim`. +```bash +sim whoami +``` -## Logging in +This also reports whether the active key is personal or workspace-scoped. Some +administrative and deployment operations require a personal key. -`sim login` uses the same browser handoff shape as `gh auth login`: the terminal -prints a pairing code and a URL, you approve in a browser, and the key comes back -over the CLI's own connection. Nothing redeemable crosses the browser leg, and -there is no loopback listener — so it works over SSH and inside containers. +Then list and run workflows: +```bash +sim workflows list +sim workflows run --input '{"ticketId":"T-4821"}' ``` -$ sim login --profile dev --endpoint http://localhost:3000 -Pairing code: K7M2-P9XT -Confirm this code matches what the browser shows before approving. +A workflow must be deployed before it can run: -http://localhost:3000/cli/auth?request=…&scope=platform -Waiting for approval… - -✓ Logged in. Key stored in /Users/you/.sim/credentials - Personal key, defaulting to a3c81b02-5f4d-4e19-9d7a-2b6c1e084f55. - Override per command with --workspace. +```bash +sim workflows deploy ``` -The approval page is where you pick the workspace — the terminal has no key yet, -so it cannot list them for you. `sim login` issues a personal key, and whichever -workspace you pick becomes only the profile's default `workspace`; it does not -limit the key to that workspace. Use `--workspace` to target another workspace -the key can access. +Workflow, knowledge-base, and workspace IDs are UUIDs. Table IDs start with +`tbl_`; file IDs start with `wf_`. Despite the prefix, `wf_` identifies a file, +not a workflow. -`sim login --workspace ` preselects a workspace in the picker, and an -existing profile's workspace preselects itself on re-login. - -### Personal and workspace keys +## Profiles -Some operations accept only a **personal** API key: secrets, knowledge chunks, -knowledge connectors, knowledge tag writes, `chat`, `audit-logs`, and most -workflow deployment writes. A workspace-scoped key gets a `FORBIDDEN` response -on those, under one of two codes: +A profile is a named CLI configuration. It determines: -- `WORKSPACE_KEY_OPERATION_NOT_PERMITTED` — the workspace-scoped operations, - which is most of the list: secrets, knowledge, `chat`, and the deployment - writes. -- `PRINCIPAL_KIND_NOT_PERMITTED` — the organization-scoped ones, which never go - through workspace authorization at all. `audit-logs` is the one in this list. +- which Sim deployment to use +- which API key to authenticate with +- which workspace to target by default +- how command output is formatted -Match on either when you are branching on the refusal. `sim whoami` reports -which kind you hold on its `Key type` row, and `sim meta status` reports the -same thing as `personal` or `workspace` alongside the rest of the key's state: +If you do not specify a profile, the CLI uses `default`. Select another profile +with `--profile`, its short form `-P`, or `SIM_PROFILE`: ```bash -$ sim meta status --output json -{ - "v2Enabled": true, - "keyType": "personal", - "expiresAt": null -} +sim workflows list --profile production +sim -P production logs list +SIM_PROFILE=production sim tables list ``` -`sim whoami --no-verify` stays offline and so cannot read the key type; it -prints `not checked` instead. +Unknown profile names fail with the configured profile list and a suggested +match when available. `login` and `configure` are the exceptions because they +can create a new profile. -`sim logout` removes the stored key. A shared workspace profile cannot remove -its authentication profile's key; use `sim logout --all --profile ` to -remove only the workspace profile. An authentication profile cannot be removed -entirely while workspace profiles reference it. Logging out does not revoke a -key — do that in Settings → API keys. +There are two common ways to create profiles. -## Commands +### Use one login with several workspaces -The commands below are the common ones. The complete reference — every group, -subcommand, argument, and flag, generated from this package — is at -[docs.sim.ai/cli/commands](https://docs.sim.ai/cli/commands). - -Plural resource names are canonical. Most plural top-level resource groups also -accept their singular form — `sim table list`, `sim file get`, and -`sim workflow get` are equivalent to their plural spellings. The groups with a -singular alias are `audit-logs`, `credentials`, `custom-tools`, `files`, `logs`, -`mcp-servers`, `secrets`, `skills`, `tables`, `workflows`, and `workspaces`; -`blocks`, `tools`, `chat-deployments`, `connector-types`, and -`workflow-mcp-servers` are plural-only. `sim --help` lists each group with the -aliases it actually accepts. - -`knowledge` also accepts the shorter `kb` alias. +After `sim login`, create another profile that shares the active profile's API +key but has its own default workspace: ```bash -sim workflows ls [path] [--search ] [--limit ] -sim workflows list [--folder ] [--deployed-only] [--limit ] -sim workflows get -sim workflows update [--name ] [--description ] [--folder ] -sim workflows mv -sim workflows deploy|undeploy|rollback -sim workflows run [--input ] [--select-output …] [--async] -sim workflows runs list --workflow [--status ] -sim workflows runs get --workflow [--include-output] -sim workflows runs cancel --workflow -sim workflows runs resume --workflow --context [--input ] - -sim logs list [--level error] [--workflow …] [--trigger …] [--start-date ] -sim logs get - -sim audit-logs list [--organization ] [--all-workspaces] -sim audit-logs get [--organization ] - sim workspaces list -sim workspaces get -sim workspaces members - -sim tables ls [path] [--search ] [--limit ] -sim tables list [--folder ] -sim tables get -sim tables update [--name ] [--description ] [--folder ] -sim tables mv -sim tables columns create|update|delete|run -sim tables rows list [--limit ] -sim tables rows create --data -sim tables rows create --rows -sim tables rows query [--filter ] [--sort ] [--limit ] -sim tables rows query --filter '{"all":[{"field":"status","op":"eq","value":"active"}]}' -sim tables upsert --data -sim tables rows batch-delete (--row … | --filter ) --yes - -sim files ls [path] [--search ] [--limit ] -sim files list [--folder ] -sim files describe -sim files get [-o ] # stdout by default -sim files create --name [--folder ] [--content ] [--encoding utf-8|base64] -sim files upload [--name ] [--folder ] -sim files share get -sim files share set --is-active [--auth-type public|password|email|sso] -sim files mv --file-ids … [--to ] -sim files batch-delete --file-ids … --yes -sim files delete --yes - -sim knowledge ls [path] [--search ] [--limit ] -sim knowledge list [--folder ] -sim knowledge get -sim knowledge update [--name ] [--description ] [--folder ] -sim knowledge mv -sim knowledge search --query --kb … [--search-mode vector|hybrid] - -sim knowledge documents list [--search ] -sim knowledge documents get -sim knowledge documents upload [--tag ...] -sim knowledge documents update [--filename ] [--enabled] -sim knowledge documents batch-update --operation enable|disable -sim knowledge documents delete --yes - -sim billing status [--all-workspaces] -sim billing logs [--period 7d] [--source sim-chat] [--limit ] [--all-workspaces] +sim profile add acme --workspace +sim --profile acme whoami ``` -The `sim-chat` billing source combines Copilot and workspace chat usage. -Organization audit logs require a personal API key; `--organization` defaults -to your only organization and is needed only when you belong to more than one. Commands with -`--all-workspaces` otherwise default to the workspace in the active profile. +If you omit `--workspace` in an interactive terminal, the CLI asks you to choose +one. The new profile stores an `auth_profile` reference to the active login; it +does not copy the API key. -`workflows runs get` is the lightweight status and polling resource. -`--workflow` names the parent resource, while the run ID remains positional. -For a paused run, its status includes the context ID needed by `resume`. -`logs get` is the full diagnostic resource. It keeps the default human output -concise; add `--trace` for the expanded recursive trace with span inputs, -outputs, errors, timing, and cost. JSON and YAML retain the complete structured -response. +### Use a separate account or deployment -`sim logs get` keeps the default human output concise. Use JSON or YAML to -inspect its complete `executionData` and recursive `traceSpans` tree: +Run `login` with a new profile name. Add `--endpoint` when the profile should use +a self-hosted or local deployment: ```bash -sim logs get --trace -sim logs get --output json | jq '.traceSpans' -sim logs list --include-trace-spans --output json +sim login --profile work +sim login --profile local --endpoint http://localhost:3000 ``` -Workflow output selectors use `blockName.field` syntax, such as -`--select-output agent_1.content`; fields that are not produced are omitted. +Each of these profiles stores its own API key. The endpoint selected during +login is saved with the profile. -`ls` is a directory view: it combines the resources at its optional path with -that folder's direct child folders. It never includes deeper descendants. Its -`ref` column is the resource ID or canonical folder path to pass to the next -command. Use `list` when you want resources only, or `folders ls` when you want -folders only. - -Each folder-backed resource has the same path commands: +### View and change profiles ```bash -sim tables ls Reports -sim tables folders ls --parent Reports -sim tables mkdir Reports/Quarterly -sim tables folders create Reports/Quarterly -sim tables folders mv Reports/Quarterly Archive/Quarterly -sim tables folders delete Archive/Quarterly --yes -sim tables folders delete Archive --recursive --yes +sim profiles +sim configure --profile work +sim configure --profile work --set-workspace +sim configure --profile work --set-output json +sim configure --profile local --set-endpoint http://localhost:3000 +sim whoami --profile work ``` -`mkdir` is the concise form of `folders create`. Replace `tables` with `files`, -`workflows`, or `knowledge`. The leading `/` is optional on API inputs; the API -returns the canonical leading-slash form. Omit the `ls` path to list root. - -### List inputs +`sim profiles` marks the active profile with `*`. Running `sim configure` with +no setting flags prints the saved settings for that profile. -Primitive lists take space-separated values. Prefix a path with `@` to read -one value per line, or use `@-` to read the list from stdin. +Non-secret settings are stored in `~/.sim/config`. API keys are stored separately +in `~/.sim/credentials`, which is written with `0600` permissions. Set +`SIM_CONFIG_DIR` to use a different directory. -```bash -sim files mv --file-ids wf_3Kq9tVbN2xLpR7sWmZ4dY wf_8Jd5cHy1QnT6vXbA0rEuP --to Archive -sim files mv --file-ids @file-ids.txt --to Archive -printf 'wf_3Kq9tVbN2xLpR7sWmZ4dY\nwf_8Jd5cHy1QnT6vXbA0rEuP\n' | sim files mv --file-ids @- --to Archive -``` +For each setting, the CLI uses the first available value in this order: -File IDs carry a `wf_` prefix, as above. Workflow, knowledge-base, and -workspace IDs are bare UUIDs, and table IDs are `tbl_`-prefixed — the `wf_` -prefix belongs to files, not workflows. +1. command-line flag +2. environment variable +3. selected profile +4. built-in default -Arrays of objects remain JSON inputs because they cannot be represented as a -flat list without losing structure. +`sim whoami` shows both the resolved values and where each one came from. -### Secret values +## Useful commands -`sim secrets set` takes the same `@` convention for its `--value`. Passing a -secret inline exposes it to shell history and to anything reading the process -list, so prefer a file or stdin; the contents are sent verbatim, with no -trimming. A value that genuinely begins with `@` is written `@@`, and only the -leading `@` is dropped. Omit `--value` entirely and the terminal prompts for it -without echoing. +Run `--help` at any level to see the available subcommands and flags: ```bash -sim secrets set STRIPE_KEY --scope workspace --value @stripe.key -op read op://vault/stripe/key | sim secrets set STRIPE_KEY --scope workspace --value @- -sim secrets set MENTION --scope workspace --value @@channel # the literal @channel +sim --help +sim workflows --help +sim tables rows query --help ``` -`--unredacted` marks a workspace secret whose value may appear in run logs and -model-visible content; `--no-unredacted` restores redaction. Omit both and the -secret keeps whatever it had. Both apply only to `--scope workspace`. +The commands you will use most often are: -### Filtering table rows - -`--filter` takes the same predicate tree the API uses — `all` (AND) or `any` -(OR) groups of `{field, op, value}` conditions, nestable. It's JSON because the -grammar is a tree; there's no honest flag encoding for it. - -```bash -sim tables rows query tbl_123 \ - --filter '{"all":[{"field":"status","op":"eq","value":"open"}, - {"field":"score","op":"gt","value":10}]}' \ - --sort '[{"field":"score","direction":"desc"}]' --limit 50 +| Task | Command | +| --- | --- | +| Ask Sim about the workspace | `sim chat "Which workflows failed today?"` | +| List or inspect workflows | `sim workflows list`, `sim workflows get ` | +| Deploy or run a workflow | `sim workflows deploy `, `sim workflows run ` | +| Follow a workflow run | `sim workflows run --follow` | +| Inspect workflow runs | `sim workflows runs list --workflow ` | +| Find errors | `sim logs list --level error`, `sim logs follow` | +| Inspect a run trace | `sim logs get --trace` | +| Work with tables | `sim tables list`, `sim tables rows query ` | +| Import a CSV | `sim tables import ./data.csv` | +| Upload or download files | `sim files upload ./report.pdf`, `sim files get ` | +| Search knowledge bases | `sim knowledge search --query "refund policy" --kb ` | +| Upload a knowledge document | `sim knowledge documents upload ./handbook.pdf` | +| Manage integration credentials | `sim credentials --help` | +| Manage workspace secrets | `sim secrets list`, `sim secrets set ` | + +Commands follow this general shape: + +```text +sim [sub-resource] [arguments] [options] ``` -`--sort` is JSON for the same reason: it is an ordered list of keys, each with a -`field` and a `direction` of `asc` or `desc`. +Many plural top-level resource names also accept a singular spelling, so +`sim workflow get ` and `sim workflows get ` are +equivalent. Not every group has a singular alias; `sim --help` shows the exact +aliases. `knowledge` also has the `kb` alias. -Row columns are discovered at runtime from the returned data, unioned across the -page so a sparse row doesn't hide a column. +For workflows, tables, files, and knowledge bases, `list` returns resources +only. `ls [path]` returns the resources and direct child folders at a path: -Deletions require an explicit selector *and* `--yes`; there is no "delete -everything" default. +```bash +sim workflows ls /Support +sim files ls /Reports +``` -### Output formats +See the [command reference](https://docs.sim.ai/cli/commands) for every command, +argument, and flag. -Output format can be selected per command with `--output`, saved as a profile -default with `sim configure --set-output `, or set ambiently with -`SIM_OUTPUT` for CI: +## JSON input and output -| Format | For | -| --- | --- | -| `table` | reading (default) | -| `json` | piping into `jq` | -| `yaml` | piping into anything that reads YAML | -| `text` | shell loops — tab-separated, no header, no colour | - -`json` and `yaml` emit the API's **raw** values, not the table's formatting — a -duration stays `1500`, not `"1.5s"` — so switching format never changes the data. -`text` uses the rendered cells, since it is meant for shell plumbing rather than -parsing. +Human-readable tables are the default. Use JSON or YAML when another program +will consume the result, and `text` for tab-separated shell output: ```bash -sim configure --set-output json # for this profile, from now on -sim configure --set-output text --profile scripts # a profile dedicated to scripting +sim workflows list --output json +sim logs list --output json | jq -r '.[].runId' +SIM_OUTPUT=yaml sim tables get +sim configure --set-output json +``` -sim --output json logs list --level error | jq -r '.[].runId' -sim logs list --level error --output json | jq -r '.[].runId' -SIM_OUTPUT=yaml sim logs list --level error > logs.yaml +JSON-valued options accept inline JSON, a file prefixed with `@`, or stdin with +`@-`: -SIM_OUTPUT=text sim files list | - while IFS=$'\t' read -r id name folder size type uploaded_by uploaded; do - echo "$id $name" - done +```bash +sim workflows run --input '{"customerId":"cus_123"}' +sim workflows run --input @input.json +printf '%s' '{"customerId":"cus_123"}' | sim workflows run --input @- ``` -An absent value is an em-dash in `table` and an **empty field** in `text`, so -emptiness tests downstream behave. +List-valued options use the same `@file` and `@-` forms, with one value per +line. Destructive commands require an explicit selector and `--yes`; they do not +default to deleting every resource when a selector is missing. -An invalid active `SIM_OUTPUT` or `output =` value fails with the accepted -formats. A valid higher-priority `--output` still overrides a stale lower tier, -so `sim --output table configure --set-output json` can repair a profile. +For secret values, prefer a prompt, file, or stdin so the value does not appear +in shell history or the process list: -## How this stays in sync with the API +```bash +sim secrets set API_KEY --scope workspace +sim secrets set API_KEY --scope workspace --value @secret.txt +printf '%s' "$API_KEY" | sim secrets set API_KEY --scope workspace --value @- +``` + +## CI and automation -`src/generated/v2-api.ts` is generated from the Zod route contracts in -`apps/sim/lib/api/contracts/v2/**` — the same contracts the routes validate -against, so a shape that disagrees with them is a shape the server would reject. -It holds every response/request type plus the operation table (method, path, -path params) the client dispatches through. +In CI, use an API key instead of `sim login`: ```bash -bun run generate:cli-api # regenerate after changing a contract -bun run check:cli-api # CI: fails if the generated file is stale -bun run check:openapi # CI: fails if the docs and contracts disagree -``` +export SIM_API_KEY="sim_..." +export SIM_WORKSPACE="" -The generated file contains only type declarations and one const — no imports — -so the `packages/*` must not import `apps/*` boundary is preserved; the script -does the crossing at build time. +sim workflows run --input @input.json --output json +``` -The OpenAPI documents under `apps/docs` are deliberately **not** generated. They -carry hand-written descriptions, examples, and error responses that Zod schemas -don't encode, so regenerating them would trade real documentation for mechanical -accuracy. `check:openapi` reconciles them against the same contracts instead — -field by field, and it parses every documented example with the real Zod schema — -so the prose survives while drift still fails the build. +Create and revoke API keys in Sim under **Settings → API keys**, and store them +in your CI provider's secret store. `sim logout` only removes a stored key from +the current machine; it does not revoke the key. -## Notes +The main environment variables are: -- Commands talk to the `/api/v2` surface, which returns `{ data }` and - `{ data, nextCursor }`. List commands auto-page up to `--limit`. +| Variable | Purpose | +| --- | --- | +| `SIM_PROFILE` | Profile to use | +| `SIM_ENDPOINT` | Sim deployment URL | +| `SIM_API_KEY` | API key, usually for CI | +| `SIM_WORKSPACE` | Workspace to target | +| `SIM_OUTPUT` | `table`, `json`, `yaml`, or `text` | +| `SIM_CONFIG_DIR` | Directory containing CLI config and credentials | +| `SIM_TIMEOUT_SECONDS` | Per-request timeout; `0` waits indefinitely | +| `SIM_DEBUG` | Print request diagnostics to stderr | + +## Documentation + +- [CLI documentation](https://docs.sim.ai/cli) +- [Command reference](https://docs.sim.ai/cli/commands) +- [Authentication](https://docs.sim.ai/cli/authentication) +- [Profiles and configuration](https://docs.sim.ai/cli/configuration) +- [Scripting](https://docs.sim.ai/cli/scripting) +- [Troubleshooting](https://docs.sim.ai/cli/troubleshooting) ## License diff --git a/packages/sim-setup/README.md b/packages/sim-setup/README.md index 3b40c8c5fe4..d21e8555ede 100644 --- a/packages/sim-setup/README.md +++ b/packages/sim-setup/README.md @@ -1,17 +1,272 @@ -# sim-setup +# Sim Setup -Set up and manage a self-hosted Sim installation. +`sim-setup` is the installer and management tool for a self-hosted +[Sim](https://sim.ai) deployment. Sim is a workspace for building, deploying, +and managing AI agents and workflows. + +For an npm user, `sim-setup` creates a Docker Compose installation from published +Sim images. It generates the required secrets, writes the deployment files, +starts the containers, runs database migrations, and checks that the application +is healthy. It does not clone the Sim repository. + +This package installs the Sim server. To manage workflows, tables, files, and +other resources in a running Sim workspace, use the separate +[`sim` CLI](https://www.npmjs.com/package/sim). + +## Requirements + +- Node.js 20 or newer +- Docker with the Compose plugin +- Ports `3000`, `3002`, and, by default, `5432` available +- At least 12 GB of system memory and 20 GB of free disk for a small installation + +Allocate at least 8 GB of memory to Docker for reliable workflow execution. +Docker Desktop, OrbStack, Colima, and Docker Engine are supported as long as the +`docker` command can reach the daemon. + +## Install and run + +You normally do not need to install the package globally: ```bash npx sim-setup ``` -Outside a Sim source checkout, the command creates a Docker Compose installation using published -images. Inside a Sim source checkout, use `bun run sim-setup` to expose the complete development -and deployment wizard. +To install it globally instead: + +```bash +npm install --global sim-setup +sim-setup +``` + +The examples below use `npx`; omit it if you installed the package globally. + +The default standalone setup creates a `sim` directory under the current +directory: + +```text +sim/ +├── .env +├── .sim-setup.json +└── docker-compose.prod.yml +``` + +Use `--dir` to choose an explicit location: + +```bash +npx sim-setup --dir /srv/sim +``` + +When setup finishes, open [http://localhost:3000](http://localhost:3000) and +create the first account. + +## What the setup wizard does + +The wizard: + +1. checks Docker, available ports, memory, and disk space +2. creates or reuses the installation directory +3. generates authentication, encryption, internal API, and scheduler secrets +4. optionally connects Sim Chat and model providers +5. writes `.env` and the managed production Compose file +6. starts PostgreSQL, Redis, the Sim application, realtime, and scheduled jobs +7. runs migrations and waits for the health checks to pass + +Choose **Quick** for sensible defaults and the fewest questions. Choose +**Custom** to configure additional options such as object storage, email, +sign-in providers, security settings, and self-hosted feature flags. Skip the +prompt with: + +```bash +npx sim-setup --quick +``` + +The wizard detects an existing installation. Re-running it lets you keep and +check the current configuration, review and update it, or archive the current +`.env` and build a new configuration. If setup fails partway through, fix the +reported problem and run the same command again; completed configuration is +preserved. + +## Chat and model access + +Sim can run without the optional Chat API key. If you skip Chat setup, the +wizard hides the Chat module instead of leaving it enabled but unusable. Connect +or replace the key later with: + +```bash +npx sim-setup add chat +npx sim-setup start +``` + +Agent blocks also need access to a model provider. Configure provider keys in a +workspace in the Sim UI, pass supported keys such as `OPENAI_API_KEY` or +`ANTHROPIC_API_KEY` into the setup environment, or add deployment-wide model +configuration later: + +```bash +npx sim-setup add llm +npx sim-setup start +``` + +For Docker Compose installations, `add` updates `.env` but does not recreate the +application container. Run `npx sim-setup start` afterward to apply the changed +environment. `restart` only restarts containers with their current configuration. + +## Manage the installation + +Run commands from the installation directory or pass `--dir ` to target a +specific installation. + +| Command | What it does | +| --- | --- | +| `npx sim-setup status` | Show detected installations, container state, and app health | +| `npx sim-setup logs` | Follow the last 100 lines of Docker Compose logs | +| `npx sim-setup start` | Start or reconcile the containers; data is kept | +| `npx sim-setup stop` | Stop containers without removing them | +| `npx sim-setup restart` | Restart the current containers | +| `npx sim-setup update` | Refresh the managed Compose file, pull images, recreate services, and run migrations | +| `npx sim-setup down` | Remove containers but keep data volumes | +| `npx sim-setup reset` | Archive `.env`, remove containers, and delete managed data volumes | + +`down` and `reset` are deliberately different. Use `down` when you want to +remove containers and bring the same installation back later. `reset` is a +destructive fresh start and asks for confirmation before deleting data. + +### Check configuration + +`config` reports which effective configuration sources, capabilities, and OAuth +integrations were detected. It does not print secret values: + +```bash +npx sim-setup config +``` + +`doctor` validates environment files, required values, cross-service +consistency, and live dependencies: + +```bash +npx sim-setup doctor +npx sim-setup doctor --fix +npx sim-setup doctor --json +``` + +Use `config` to answer “what is configured?” and `status` to answer “what is +running and healthy?” + +### Add or change capabilities -To connect or replace the Chat API key without rerunning the full wizard: +Configure one capability without walking through the complete wizard: ```bash +npx sim-setup add email +npx sim-setup add storage +npx sim-setup add sandbox +npx sim-setup add jobs +npx sim-setup add cache +npx sim-setup add knowledge +npx sim-setup add knowledge-embeddings npx sim-setup add chat +npx sim-setup add llm +npx sim-setup add integration slack ``` + +Run `npx sim-setup start` after changing a Docker Compose capability so the app +container receives the new environment. + +## Updating + +Update a Docker Compose installation with: + +```bash +npx sim-setup update +npx sim-setup status +``` + +The update command keeps Docker volumes, applies the current managed Compose +file, pulls the version selected by `SIM_VERSION`, and runs migrations. If +`SIM_VERSION` is unset, the deployment tracks `latest`. + +For production, pin an explicit version, back up the database first, and read +the [upgrade guide](https://docs.sim.ai/platform/self-hosting/upgrades). Docker +Compose updates briefly interrupt the application because Compose does not +provide rolling deployments. + +## Files, secrets, and data + +The generated `.env` contains credentials and encryption keys. It is written +with owner-only permissions and must not be committed to source control. + +Back up `.env` securely outside the server before using the deployment for real +data. In particular, `ENCRYPTION_KEY` and `API_ENCRYPTION_KEY` protect stored +credentials and API keys. A database backup restored without the matching keys +contains data that Sim cannot decrypt. + +PostgreSQL data lives in a Docker volume. These commands preserve it: + +- `start` +- `stop` +- `restart` +- `update` +- `down` + +`reset` deletes managed volumes. It archives `.env` beside the installation +before doing so, but that local archive is not a substitute for an off-machine +backup. + +The default local file-storage fallback is different: uploaded files live inside +the application container, not in a managed volume. They can be lost when the +container is removed or recreated, including during `down` or `update`. +Configure object storage before keeping files you care about. + +## Production deployments + +The generated Compose installation is suitable for local evaluation and a +single-node deployment. Before exposing it publicly, configure at least: + +- a public application URL and TLS reverse proxy +- database and `.env` backups +- durable object storage for uploaded files +- email delivery for invitations and email-based authentication +- OAuth applications for integrations you plan to use +- a pinned Sim version and an upgrade procedure + +See the [Docker deployment guide](https://docs.sim.ai/platform/self-hosting/docker) +and the complete [self-hosting documentation](https://docs.sim.ai/platform/self-hosting). + +## Working from the Sim source repository + +Inside a cloned Sim repository, use: + +```bash +bun run sim-setup +``` + +The source checkout adds local development and Kubernetes modes: + +```bash +bun run sim-setup --mode dev +bun run sim-setup --mode k8s +``` + +Standalone npm use supports Docker Compose mode only. Development and Kubernetes +modes need source-only files and are rejected outside a complete checkout. + +## Help + +```bash +npx sim-setup --help +npx sim-setup --version +``` + +Further documentation: + +- [Self-hosting overview](https://docs.sim.ai/platform/self-hosting) +- [Docker Compose](https://docs.sim.ai/platform/self-hosting/docker) +- [Environment variables](https://docs.sim.ai/platform/self-hosting/environment-variables) +- [Upgrades](https://docs.sim.ai/platform/self-hosting/upgrades) +- [Troubleshooting](https://docs.sim.ai/platform/self-hosting/troubleshooting) +- [Verification checklist](https://docs.sim.ai/platform/self-hosting/verify) + +## License + +Apache-2.0