CLI (Command Line Interface)

Prerequisite: Install Node.js 22 or newer.

To run the CLI without a global installation:

npx @sr-connect/cli

To install the CLI globally for everyday use (recommended):

npm i -g @sr-connect/cli
sr-connect

The rest of this guide uses the sr-connect command.

Commands consist of a group and a verb (for example, in script get, script is the group and get is the verb). Run a group name on its own to list its verbs, or run sr-connect to list all available groups.

Clone a workspace into a local directory:

sr-connect local-workspace clone my-workspace

Select the team, workspace, and environment when prompted. Specify a target directory name, or omit it to clone into the current working directory. The CLI creates a Node TypeScript project:

my-workspace/
  scripts/                    one .ts file per script
    api/                      generated code for your API connections, do not edit
      <API connection path>/
        index.ts
  test-payloads/              your event listeners' test payloads, as JSON files
    <App→Event (listenerId)>/
      <payload name>.json
  node/                       API mocks and Jest setup for local tests
    tests/                    your own tests go here
    apiRegistry.ts
    runtimeMocks.ts
    global.d.ts
    jest.config.ts
    tsconfig.json
  .vscode/
    extensions.json
  ev-params.ts                types for your environment parameters, never their values
  README.md                   the workspace README
  package.json                PS! do not add dependencies directly, use `sr-connect package add` instead, adding dev dependencies locally is safe
  tsconfig.json
  tsconfig.base.json
  eslint.config.js
  .prettierrc
  .gitignore
  pnpm-workspace.yaml
  workspace.json              workspace metadata file, do not edit

Manage dependencies and test scripts using standard package manager workflows:

cd my-workspace
pnpm install      # installs the dependencies
pnpm typecheck    # checks your scripts and tests with the TypeScript compiler
pnpm test         # runs your Jest tests in node/tests against API and runtime mocks

Cloning performs a read-only operation and does not alter the server workspace. Sensitive parameter values and passwords are never written to disk, making the repository safe to commit.

When cloning into an existing local workspace directory, the CLI prompts before overwriting files. The following customisable configuration files and directories are preserved:

• Tooling configurations: tsconfig.json, tsconfig.base.json, eslint.config.js, .prettierrc, .gitignore, pnpm-workspace.yaml, and .vscode/extensions.json.

• Local testing files in node/: apiRegistry.ts, runtimeMocks.ts, global.d.ts, jest.config.ts, and tsconfig.json.

• Custom package.json entries (except the managed dependencies block). Always use sr-connect package add to register server dependencies. Adding packages under devDependencies is safe and preserved across clones.

For more details, see Work from a local copy.

Commands executed inside a cloned workspace directory automatically target the team, workspace, and environment declared in workspace.json (do not edit this file). The CLI displays the active scope and requests confirmation.

Direct CLI changes affecting local files (such as saving a script or updating the README) automatically sync to your local directory without requiring an explicit re-clone. For more details, see Local sync.

sr-connect local-workspace push

sr-connect local-workspace clone     # once
# edit scripts in your IDE
pnpm typecheck && pnpm test          # fast, local
sr-connect local-workspace push      # push changes to server
sr-connect script trigger            # run it and watch the output

sr-connect workspace-lock release

Scripts execute server-side against the saved workspace state. Ensure local changes are pushed before triggering.

sr-connect script trigger

When console streaming is active, console.log, warning, and error outputs print to your terminal in real time. The CLI exits with a corresponding exit code upon failure, making it suitable for CI/CD pipelines and automated scripts.

The cli command group provides management and diagnostic utilities for the CLI tool itself:

• Session defaults:

  • Selected team, workspace, and environment parameters persist in the active terminal window for 12 hours. Clear them anytime with sr-connect cli clear-session.

• Local workspace precedence:

  • Inside a cloned directory, workspace.json settings override session defaults. Explicit command flags and environment variables take precedence over both.

• API call recording:

  • The CLI logs outbound API calls locally for seven days with sensitive credentials redacted. View logs using sr-connect cli list-api-logs.

• Crash reports:

  • If an internal CLI error occurs, diagnostic reports are stored locally. Inspect them with sr-connect cli list-crash-reports before submitting.

• Settings:

  • Run sr-connect cli settings to toggle API recording, workspace locking, local file synchronisation, crash reports, and agent feedback.

• Exit codes:

  • 0 (Success), 1 (Failure), 2 (Usage error), 3 (Authentication error), 4 (Resource not found), and 130 (Cancelled).