Kortyx Studio CLI Commands

Updated 5 days ago • October 9, 2026

The kortyx studio commands manage the local Docker-based installation, provide debugging against local or remote Studio APIs, and execute eval suites. Run them through the public kortyx package:

Local state is stored in ~/.kortyx/studio by default. Commands reuse that state, so credentials and database data survive ordinary stop, restart, CLI upgrades, and repeated starts.

Everyday commands

Good to know: Start is idempotent. Running it again is the normal way to bring back a stopped installation or apply a changed image tag or port configuration.

Start options

Choose different host ports:

Pin both Studio images to an immutable published release:

Studio image tags use the Studio release version, not the CLI package version. CLI and Studio minor versions may differ while remaining compatible through the stable Studio API protocol. studio status reports the configured image and the negotiated protocol; studio inspect rejects only an incompatible protocol major or a response that violates the advertised protocol.

Use an alternate state directory or local username:

The same --home value must be supplied to later commands. Alternatively, set KORTYX_STUDIO_HOME for the shell or automation that manages that installation.

Print or rotate local credentials

Print the current browser and SDK connection values:

Print only the server-side SDK variables for an application:

This format intentionally omits the browser password and local state path, but it still includes a secret telemetry write key. Keep the output server-side.

Replace the browser password and both application API-key secrets:

Rotation updates the local environment atomically, applies new key verifiers, recreates affected services, and attempts rollback if the application fails. The previous telemetry key becomes invalid, so update and restart every local SDK producer.

The database password and API-key pepper are deliberately preserved.

Generate credentials for remote deployment

This produces an unpersisted credential set without creating local Studio state. Store it immediately in the deployment's secret manager. It cannot be printed again later.

See Credentials and Secrets before using generated values on a server.

Publish a workflow catalog

Catalog publication is a top-level Kortyx command rather than a Studio lifecycle command:

It publishes declared workflow topology before traffic arrives without creating runs. Use --dry-run to inspect the projection locally. See Connect Your Project for the complete connection flow.

Good to know: Publication runs in your application's deployment environment. The CLI imports the application entry module and calls the telemetry API with its write key. Include it in CI/CD for each application release. For a private API, run from an allowed network, for example in a one-off ECS task using the application's release image; the GitHub runner can launch that task without reaching the private API itself. Deploying Studio does not run this command for your applications.

Reset local data

Destructive command: Reset permanently deletes the local PostgreSQL volume. It preserves generated credentials, so the next studio start creates an empty database and bootstraps those keys again.

Back up any telemetry you need before resetting. See Operations and Troubleshooting.

Read-only run and session debugging

Inspect a Studio link directly, without browser automation:

Inspection returns project context, entity details, the latest execution events, branch-aware child calls, and diagnostic findings. Findings are evidence, not an automated root-cause conclusion: retries and human interruptions may be expected. Link selectors such as call and branch are retained as context, not applied as API filters.

Lists default to 25 items over 24 hours. Use --limit (up to 100) and pass page.nextCursor as --cursor for the next page. Short time ranges are 1h, 24h, 7d, 30d, and all. Supply both --started-after and --started-before for custom ISO datetime boundaries. Run lists support --include-children; workflow metrics currently span environments.

Detail output defaults to the latest 100 events and explicitly reports omitted events, calls, and findings. Increase --event-limit when needed (up to 10000). Captured content is omitted by default; --include-content returns it only if it was captured. Resume tokens and recognizable credentials remain redacted, but arbitrary application content may still contain sensitive data. Missing telemetry/content does not prove an action did not happen.

Connect local, staging, or another project

Local Studio is automatically available as local after studio start, using its managed Studio read key. For remote access, securely inject a project-scoped read key into an environment variable, then register the API/browser URL pair:

Profiles store locators and environment-variable references in ~/.kortyx/connections.json, never raw remote keys. Use --config-home or KORTYX_CONFIG_HOME for another configuration directory. Read keys need studio:read; browser passwords and telemetry-write keys are not interchangeable. Use a different profile/key for each project, even when projects share a URL. Remote account login and project/key administration are not implemented.

For IDs, selection is --connection, then KORTYX_CONNECTION, the saved default, and finally local. Pasted URLs must match a configured Studio or API base URL; unknown or ambiguous URLs fail without sending credentials. Explicit selection must also match the pasted URL. Agents should select a connection per command instead of changing the shared default. Remote connections require HTTPS and any existing VPN/network access; redirects are not followed.

Local CLI versus remote operation

Lifecycle commands manage the local Compose stack; read commands query the Studio HTTP API. Read commands cannot execute/resume runs, approve interrupts, publish topology, or administer remote projects. The CLI does not SSH into servers, edit a remote database, or replace your cloud platform's deployment tools.

For remote environments, use Deploy on a Server, inject secrets through the platform, and operate the same container contract through your infrastructure tooling.

Eval suites and post-deployment CI

The CLI uses the same Studio API, project scopes, application targets, worker, and PostgreSQL records as the browser. It does not import your agent or obtain an end-user token. The application handles its test actor in createEvals.setup.

Configure the consumer endpoint and Studio targets first. Your connection key needs studio:read for discovery and result inspection, plus eval:run for starting and cancelling. The SDK telemetry write key cannot run evals. The application's eval service key stays on the Studio API server.

Diagnose deployment wiring

Doctor checks read/execution scopes, matching targets/environment, authenticated consumer manifest/suites and configured judge compatibility. It uses discovery GET only; it starts no workflows, model calls or saved runs. Consumer discovery wrappers may perform their own authentication. It gives safe failure categories and remedies; older APIs may return only generic unavailable diagnostics.

--target, --environment, --suite and --judge narrow the checks. Connection environment defaults apply. Use --api-url and --api-key-env instead of --connection for direct access. --json prints one report with schemaVersion: 1, status and checks; exit 0 means setup checks passed, exit 1 means a failure. Each check has id, status (passed, failed or skipped), message and optional remedy. Provider credentials, test-user tool permissions and worker execution still need a real run. Follow the complete setup recipe.

Run locally without Studio

Export the existing createEvals instance as evals (or the default export) from an application module such as src/evals/index.ts. Use a dedicated eval module that initializes the agent and suites without starting your HTTP server. TypeScript and JavaScript entries use the CLI's existing module loader and nearest tsconfig.json path aliases. The loader stays active for lazy workflow imports until execution finishes. Keep initialization synchronous; do asynchronous identity setup inside createEvals.setup.

Add a script to your application's package.json:

The command calls the exported instance's run() directly. Your existing setup, permission binding, custom executor, interrupt responders, cleanup and code judge all run in the application process. No Studio, consumer HTTP endpoint, target configuration or Studio key is required. Semantic criteria require a code judge; interaction and structured-output checks alone require no judge. Workflow models, tools and authentication still need their usual application configuration.

The CLI loads .env then overlays .env.local before importing the entry. In a monorepo it loads defaults from the Git or pnpm workspace root down to the app directory, with nearer files taking precedence. Existing shell variables always win. To select other files, repeat --env; later files override earlier ones:

For a one-line package script without repeated flags, remember paths in a gitignored .env.evals.json in the app or workspace root:

Keep the profile and referenced files owner-only (chmod 600). Relative paths in the profile resolve from its directory. The nearest profile replaces default env loading; discovery stops at a Git or pnpm workspace boundary. Explicit --env flags replace both the profile and defaults, and resolve from the invocation directory. Missing configured files fail before loading the app; credentials are never printed. The CLI handles loading directly, so no launcher script or shell exports are required. Package scripts in monorepos can forward with pnpm --filter my-agent eval.

Model credentials remain application-owned, for example OPENROUTER_API_KEY for an OpenRouter app judge. Studio's judge settings are not used by this command.

Omitting --suite runs all configured suites in definition order. --case accepts space-separated case IDs and requires --suite. --repetitions and --concurrency override the SDK's run settings; omitted flags preserve them. --export NAME selects another named instance instead of evals/default.

Interactive terminals show an animated suite progress bar, one live row per active attempt, elapsed time, and the actual setup, workflow, interrupt-response, judging and cleanup phases. Every completed step and case gets its own result, followed by a colored suite verdict and counts. Long calls keep animating; concurrent attempts remain distinct. The bar measures completed attempts, not estimated model completion. Application logs/warnings are preserved above the live display. Piped output is plain text with per-case start and step results; --no-color or NO_COLOR disables color/live progress. Explicit --color forces the interactive report, including when NO_COLOR is set. --json always disables the terminal UI. --json replaces the report with one JSON object containing schemaVersion: 1, status, aggregated counts, and full SDK runs (including observations). Keep application logs off stdout when consuming JSON. Configuration/import failures use stderr.

Exit status is 0 when all selected suites pass, 1 for failed/errored runs or configuration errors, and 130 for cancellation. Ctrl+C forwards an abort signal, allows SDK cleanup and stops later suites. Cancellation remains cooperative: app code must honor its signal. Results are returned in the terminal/JSON; this local command does not save eval records to Studio. Agent telemetry, if configured by the application, continues to follow its existing settings.

Discover and run

Local Studio uses --connection local and its managed credentials. A remote profile references an environment variable containing a project-scoped Studio key:

Profiles save URL locators and the variable name, never the remote key. Inject the key through your shell or CI secret store. Alternatively, pass --api-url and --api-key-env together for a direct connection using IDs; do not combine those flags with --connection or KORTYX_CONNECTION.

The connection environment filters discovery and history by default. Override it with --environment. If a suite exists on multiple targets, select --target. Repeat --case for multiple cases; omit it to run every case. The limits are 20 repetitions, concurrency 20, and 100 total attempts per queued run.

Start discovers the current suite revision and enqueues one request. It returns immediately with schemaVersion: 1, id, status: "queued", and studioUrl (null when the connection has no browser URL). Success means the request was accepted, not that its cases passed. A changed suite returns HTTP 409; no retry or second run is performed automatically. Refresh discovery and retry explicitly.

Inspect and cancel

Runs started through the CLI default to the configured Studio judge. Add --judge app to use the consumer's code judge. The API records the selected judge and its version; missing configuration fails before enqueuing, without fallback.

History returns the latest 100 records in the project before the CLI applies an environment filter. Run detail includes counts, case/step statuses and criterion IDs/verdicts. Suite definitions, observations, reference facts and grade reasoning require --include-content. Recognizable credentials and resume tokens remain redacted on a best-effort basis, including when content is requested.

Pasted URLs must match a configured connection; redirects are not followed. Cancellation is cooperative and does not roll back application side effects. A run may finish before cancellation arrives. Inspect its final saved status.

Optional post-deployment GitHub Actions step

Install and pin kortyx or @kortyx/cli in the application's lockfile. After your existing deployment and readiness check, enqueue a suite:

This step returns after enqueueing and does not wait for grades or gate the deployment. Inspect results in Studio or with runs get. Ensure the CI runner can reach the Studio API, and the Studio API can reach the deployed consumer endpoint. Use a key scoped to the intended project with studio:read and eval:run. Each invocation creates a new run; your deployment workflow owns trigger frequency.