---
title: "Execute a command"
method: POST
path: "/v1/exec"
tags: ["exec"]
---

# Execute a command

`POST /v1/exec`

Start a command with the given options and return a value representing the process.

This API returns a `task-id` (see the response schema and the example below),
then you need to call `/v1/tasks/{task-id}/websocket/control` and `/v1/tasks/{task-id}/websocket/stdio`
(also `/v1/tasks/{task-id}/websocket/stderr` if `split-stderr` is true) with the returned `task-id`.

## Request body

- PostExecRequest
  - `command` string[], required — The command to execute (including arguments).
  - `service-context` string — The service context to use for execution.
  - `environment` object — Environment variables to set for the command.
  - `working-dir` string — The working directory for the command.
  - `timeout` string — The timeout for the command execution (e.g., "60s", "1m").
  - `user-id` integer — The user ID to run the command as.
  - `user` string — The username to run the command as.
  - `group-id` integer — The group ID to run the command as.
  - `group` string — The group name to run the command as.
  - `terminal` boolean — Whether to allocate a pseudo-terminal.
  - `interactive` boolean — Whether the command is interactive.
  - `split-stderr` boolean — Whether to split stderr from stdout.
  - `width` integer — The width of the terminal (if applicable).
  - `height` integer — The height of the terminal (if applicable).

## Response `202`

Command execution initiated.

- PostExecResponse
  - `type` string — Response type, "sync".
  - `status-code` integer — HTTP response status code.
  - `status` string — The description of the HTTP status code. See the [IANA list](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).
  - `change` string — The Change ID of the asynchronous change.
  - `result` object
    - `environment` object — The environment variables.
    - `task-id` string, uuid — The ID of the executed task.
    - `working-dir` string — The working directory.

## Changes

> 12 revisions in range; 1 could not be searched.

- **2025-01-13** `20135041d803` — 2 info
  - api tag `exec` added
  - api tag `files` removed
- **2025-01-02** `1cb37312be6c` — 1 info
  - endpoint added
- **2024-12-22** `b3903318c3bd` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/canonical/apis/pebble-api/changes/v1/exec/post.md)

---

[API](https://skmtc.dev/canonical/apis/pebble-api.md) · [All operations](https://skmtc.dev/canonical/apis/pebble-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/canonical/pebble-api/revisions/a94f353eccac/schema)