> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getprimo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run an ad-hoc script on a device

> Run an ad-hoc script on the device for the given device ID.

The script content is sent inline (there is no script catalog) and runs on the device via FleetDM the next time it is online.

**Supported platforms:** macOS (bash/zsh), Windows (PowerShell), Linux (bash)

**Asynchronous:** the response returns immediately with `status: "pending"`. Poll the device's run history to read `output`, `exitCode` and `runtime` once the device reports back.

⚠️ **Warning:** this executes arbitrary code on the device with elevated privileges. Review the script before running it.

**Not supported:** iOS, Android, Chrome OS

<span className="badge-write">Key: Write</span><span className="badge-company">Scope: Company</span>


## OpenAPI

````yaml https://api.getprimo.com/openapi.json post /devices/{deviceId}/run-script
openapi: 3.1.1
info:
  title: Public API - BETA
  description: Read docs on https://docs.getprimo.com/
  version: '1.0'
  contact: {}
servers:
  - url: https://api.getprimo.com
security:
  - apikey: []
tags: []
paths:
  /devices/{deviceId}/run-script:
    post:
      tags:
        - Devices
      summary: Run an ad-hoc script on a device
      description: >-
        Run an ad-hoc script on the device for the given device ID.


        The script content is sent inline (there is no script catalog) and runs
        on the device via FleetDM the next time it is online.


        **Supported platforms:** macOS (bash/zsh), Windows (PowerShell), Linux
        (bash)


        **Asynchronous:** the response returns immediately with `status:
        "pending"`. Poll the device's run history to read `output`, `exitCode`
        and `runtime` once the device reports back.


        ⚠️ **Warning:** this executes arbitrary code on the device with elevated
        privileges. Review the script before running it.


        **Not supported:** iOS, Android, Chrome OS
      operationId: runDeviceScript
      parameters:
        - name: deviceId
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunDeviceScriptBody'
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunDeviceScript_Output'
components:
  schemas:
    RunDeviceScriptBody:
      type: object
      properties:
        scriptContents:
          description: >-
            The shell (bash/zsh) or PowerShell script to run on the device. Sent
            inline and executed via FleetDM.
          type: string
          minLength: 1
          maxLength: 10000
      required:
        - scriptContents
    RunDeviceScript_Output:
      type: object
      properties:
        id:
          type: string
          description: Identifier of the script run record.
        executionId:
          type: string
          description: FleetDM execution id for this run.
        scriptContents:
          type: string
          description: The script content that was executed.
        status:
          type: string
          description: >-
            Run status. `pending` until the device reports back, then
            `completed`/`errored`/`timeout`.
          enum:
            - pending
            - completed
            - errored
            - timeout
        output:
          description: Combined stdout/stderr once the run completes. Null while pending.
          anyOf:
            - type: string
            - type: 'null'
        exitCode:
          description: Process exit code once the run completes. Null while pending.
          anyOf:
            - type: number
            - type: 'null'
        runtime:
          description: Run duration in seconds once the run completes. Null while pending.
          anyOf:
            - type: number
            - type: 'null'
        createdAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        updatedAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
      required:
        - id
        - executionId
        - scriptContents
        - status
        - output
        - exitCode
        - runtime
        - createdAt
        - updatedAt
      additionalProperties: false
  securitySchemes:
    apikey:
      scheme: bearer
      bearerFormat: API key
      type: http
      description: >-
        Use your Primo API key in the Authorization header as `Bearer
        <API_KEY>`.

````