Workspace

Execute shell commands against a git repository at any point in history with optional auto-commit.

Execute Command

Run a shell command in the context of a repository. The filesystem is backed by git objects — reads are lazy, writes are held in memory. Optionally commit changes back to git in a single atomic operation.

POST /v1/repos/:slug/exec
POST /v1/repos/:namespace/:slug/exec

Permission: Write access required.

{
  "command": "echo 'hello' > greeting.txt && cat greeting.txt",
  "branch": "main",
  "cwd": "/",
  "env": { "NODE_ENV": "production" },
  "commit": true,
  "commit_message": "Add greeting file",
  "author": { "name": "Agent", "email": "agent@example.com" }
}

Fields

Field	Required	Description
`command`	Yes	Shell command to execute (max 10,000 chars)
`branch`	No	Target branch (default: `"main"`). Used as filesystem source and commit target
`ref`	No	Load filesystem from this ref (commit SHA, branch, or tag). Overrides `branch` for reads
`cwd`	No	Working directory (default: `"/"`)
`env`	No	Environment variables
`commit`	No	Commit changed files after execution (default: `false`)
`commit_message`	If `commit=true`	Commit message
`author`	No	`{ name, email }` for the commit author

When ref is provided, the filesystem is loaded from that specific commit. If you also want to commit changes, you must provide branch — it determines which branch receives the new commit.

Response `200`

{
  "stdout": "hello\n",
  "stderr": "",
  "exit_code": 0,
  "changed_files": ["greeting.txt"],
  "commit_sha": "a1b2c3...",
  "execution_time_ms": 42
}

Field	Description
`stdout`	Standard output
`stderr`	Standard error
`exit_code`	Process exit code
`changed_files`	List of files created or modified
`commit_sha`	Commit SHA (only when `commit=true`)
`execution_time_ms`	Execution time in milliseconds

Use Cases

Execute on a specific commit in history

Use ref to load the filesystem from any commit SHA, branch, or tag:

{
  "command": "cat package.json | grep version",
  "ref": "a1b2c3d4e5f6..."
}

Execute on an old commit and commit the result to a branch

{
  "command": "npm run fix-legacy",
  "ref": "v1.0.0",
  "branch": "hotfix-v1",
  "commit": true,
  "commit_message": "fix: backport security patch to v1",
  "author": { "name": "Agent", "email": "agent@example.com" }
}

Install dependencies and commit lockfile

{
  "command": "npm install express",
  "branch": "main",
  "commit": true,
  "commit_message": "chore: add express dependency",
  "author": { "name": "Agent", "email": "agent@example.com" }
}

Run a build without committing

{
  "command": "npm run build",
  "branch": "main",
  "commit": false
}

SDK Example

// Execute on current branch HEAD
const { data } = await git.workspace.exec("my-repo", {
  command: "ls -la",
  branch: "main",
});
console.log(data.stdout);

// Execute on a specific commit SHA
const { data } = await git.workspace.exec("my-repo", {
  command: "cat package.json",
  ref: "a1b2c3d4...",
});

// Execute on an old commit, commit result to a branch
const { data } = await git.workspace.exec("my-repo", {
  command: "npm run migrate",
  ref: "v1.0.0",
  branch: "hotfix",
  commit: true,
  commit_message: "fix: apply migration",
  author: { name: "Agent", email: "agent@example.com" },
});
console.log(data.commit_sha);

With namespaces:

const { data } = await git.workspace.exec(
  { namespace: "alice", slug: "my-repo" },
  {
    command: "npm test",
    ref: "feature-branch",
  },
);

Multi-Repo Execution

Execute a command across multiple repositories mounted at virtual paths (/{slug}/).

POST /v1/workspace/exec

Permission: Read or write access to all specified repos.

{
  "repos": [
    { "slug": "frontend", "branch": "main" },
    { "slug": "backend", "branch": "main" },
    { "slug": "shared-lib", "namespace": "libs" }
  ],
  "command": "grep -r 'API_VERSION' .",
  "commit": false
}

Fields

Field	Required	Description
`repos`	Yes	Array of repos to mount (max 10)
`repos[].slug`	Yes	Repository slug
`repos[].branch`	No	Branch name (default: repo's default branch)
`repos[].namespace`	No	Namespace for scoped repos
`command`	Yes	Shell command to execute (max 10,000 chars)
`cwd`	No	Working directory
`env`	No	Environment variables
`commit`	No	Commit changes per repo (default: `false`)
`commit_message`	If `commit=true`	Commit message
`author`	No	`{ name, email }` for commit author

Each repo is mounted at /{slug}/ in the virtual filesystem. The command runs across all of them.

Response `200`

{
  "stdout": "frontend/src/config.ts:  API_VERSION: '2'\nbackend/src/config.ts:  API_VERSION: '2'\n",
  "stderr": "",
  "exit_code": 0,
  "changed_files": {},
  "commits": {},
  "repos_mounted": ["frontend", "backend", "shared-lib"],
  "execution_time_ms": 1200
}

When commit=true, changes are committed independently per repo:

{
  "changed_files": {
    "frontend": [{ "path": "src/version.ts", "action": "modify" }],
    "backend": [{ "path": "src/version.ts", "action": "modify" }]
  },
  "commits": {
    "frontend": "a1b2c3...",
    "backend": "d4e5f6..."
  }
}

SDK Example

// Search across repos
const { data } = await git.workspace.multiExec({
  repos: [
    { slug: "frontend" },
    { slug: "backend" },
  ],
  command: "grep -r 'deprecated' .",
});
console.log(data.stdout);

// Modify files across repos and commit
const { data } = await git.workspace.multiExec({
  repos: [
    { slug: "frontend", branch: "main" },
    { slug: "backend", branch: "main" },
  ],
  command: "sed -i 's/v1/v2/g' */src/config.ts",
  commit: true,
  commit_message: "chore: bump API version to v2",
  author: { name: "Agent", email: "agent@example.com" },
});
console.log(data.commits); // { frontend: "a1b2...", backend: "d4e5..." }

WorkspaceCopy MarkdownOpen

On this page

Workspace