---
title: "Run shell command"
method: POST
path: "/session/{sessionID}/shell"
---

# Run shell command

`POST /session/{sessionID}/shell`

Execute a shell command within the session context and return the AI's response.

## Path parameters

- `sessionID` string, required

## Query parameters

- `directory` string

## Request body

- object
  - `agent` string, required
  - `model` object
    - `providerID` string, required
    - `modelID` string, required
  - `command` string, required

## Response `200`

Created message

- AssistantMessage
  - `id` string, required
  - `sessionID` string, required
  - `role` 'assistant', required
  - `time` object, required
    - `created` number, required
    - `completed` number
  - `error` union
    - ProviderAuthError
      - `name` 'ProviderAuthError', required
      - `data` object, required
        - `providerID` string, required
        - `message` string, required
    - UnknownError
      - `name` 'UnknownError', required
      - `data` object, required
        - `message` string, required
    - MessageOutputLengthError
      - `name` 'MessageOutputLengthError', required
      - `data` object, required
    - MessageAbortedError
      - `name` 'MessageAbortedError', required
      - `data` object, required
        - `message` string, required
    - StructuredOutputError
      - `name` 'StructuredOutputError', required
      - `data` object, required
        - `message` string, required
        - `retries` number, required
    - ContextOverflowError
      - `name` 'ContextOverflowError', required
      - `data` object, required
        - `message` string, required
        - `responseBody` string
    - APIError
      - `name` 'APIError', required
      - `data` object, required
        - `message` string, required
        - `statusCode` number
        - `isRetryable` boolean, required
        - `responseHeaders` object
        - `responseBody` string
        - `metadata` object
  - `parentID` string, required
  - `modelID` string, required
  - `providerID` string, required
  - `mode` string, required
  - `agent` string, required
  - `path` object, required
    - `cwd` string, required
    - `root` string, required
  - `summary` boolean
  - `cost` number, required
  - `tokens` object, required
    - `total` number
    - `input` number, required
    - `output` number, required
    - `reasoning` number, required
    - `cache` object, required
      - `read` number, required
      - `write` number, required
  - `structured` unknown
  - `variant` string
  - `finish` string
  - `stepCapped` boolean
  - `stuckNudged` boolean
  - `stuckAborted` boolean

## Other responses

- `400` — Bad request
- `404` — Not found

## Changes

- **2026-08-06** `4e11f1aed2fd` — 2 info
  - added the optional property `stuckAborted` to the response with the `200` status
  - added the optional property `stuckNudged` to the response with the `200` status
- **2026-06-29** `e7837fb0de8f` — 1 info
  - added the optional property `stepCapped` to the response with the `200` status
- **2026-02-12** `7eb1c31fb938` — 2 info
  - added the optional property `structured` to the response with the `200` status
  - added `#/components/schemas/StructuredOutputError` to the `error` response property `anyOf` list for the response status `200`
- **2026-02-11** `8f23f1074f57` — 1 info
  - added the optional property `tokens/total` to the response with the `200` status
- **2026-02-09** `3e70f65f33fa` — 1 info
  - added `#/components/schemas/ContextOverflowError` to the `error` response property `anyOf` list for the response status `200`

[Full history](https://skmtc.dev/cyberstrikeus/apis/cyberstrike/changes/session/:sessionID/shell/post.md)

---

[API](https://skmtc.dev/cyberstrikeus/apis/cyberstrike.md) · [All operations](https://skmtc.dev/cyberstrikeus/apis/cyberstrike/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cyberstrikeus/cyberstrike/revisions/60718ff578c8/schema)