Skip to main content
Install the SDK and CLI in a pnpm project:
For a new Agent, run simple init. To synchronize an existing production branch, run:
agent.ts is the desired state. simple.lock.json records the remote Agent, selected branch and head commit, graph identities, and immutable Action heads. Commit both files. Pull refuses to overwrite local changes. Reconcile them first, or pass --force only when you intentionally want production to replace the local source. If --branch is omitted, the CLI follows the product’s most-recently-updated branch selection.

​
Action-first authoring

Define integrations with action.http, action.code, action.customDataQuery, action.customDataSearch, or action.knowledgeBaseSearch. Attach an Action to a prompt with action.callable, or execute it deterministically with an Action node or action.run.
New authoring never emits legacy tool assignments or HTTP graph nodes. A pull uses defineAgentSnapshot(...) when necessary to preserve every current Agent v2 node and legacy field losslessly; you can refactor that snapshot to the ergonomic API deliberately.

​
Validate and publish

Publish validates the complete project on the server before mutation, checks Agent and branch metadata plus the relevant Action heads, creates or revises changed Actions with retry-safe identities, and finally creates one Agent commit pinned to those exact versions. If remote state changed, publish stops and asks you to pull or upgrade instead of overwriting it. simple actions upgrade rewrites a pulled defineAgentSnapshot(...) with the accepted remote Action values and version pins. For ergonomic defineAgent(...) source, update the Action definition to match the remote head first; the CLI refuses to make the lockfile disagree with source.

​
Organization resources

Tags, analyzers, scorecards, and post-call workflows belong to the organization rather than to an Agent commit, and an Agent references them by UUID. The CLI creates and lists them directly:
Each list prints <uuid> <name> <details> and accepts --json for the raw payload, which is how you collect the UUIDs that agent.ts, a scorecard section, or a workflow filter needs. Each resource is created from a JSON definition passed with --file <path> (--file - reads stdin), from command flags, or from both, with flags overriding the file. Definitions are camelCase, reference other resources by UUID, and are validated locally before anything is sent.
--output covers string, number, and boolean analyzers and --output-enum covers enums; nested object and array outputs are authored in a definition file:
A scorecard, and each of its sections, can be restricted to calls carrying certain tags. callTagUuids is the shorthand for “any of these tags”; callTagFilter expresses the full rule in disjunctive normal form, where groups are ORed and the conditions inside a group are ANDed with any_of, all_of, or none_of:
A post-call workflow runs its actions in order against one Agent branch once a call ends, so it is always created from a file. Filter actions gate the remaining actions on an analyzer result, and action identities are generated unless the definition names them:
Inside a pulled project the branch recorded in simple.lock.json is used, so --agent and --branch are only needed elsewhere. An agentBranchUuid in the definition pins the branch outright and overrides both.

​
CLI authentication

simple login opens PropelAuth in your browser and uses Authorization Code + PKCE. When your account belongs to more than one organization, the CLI asks which organization to use. It stores the rotating refresh token with user-only permissions and refreshes short-lived access tokens automatically. The CLI is OAuth-only and uses the signed-in user’s existing Agent and Action permissions. The published CLI includes Simple’s public OAuth client configuration and registered localhost callback. No client secret is used by the CLI.