commands

Creates, updates, deletes, gets or lists a commands resource.

Overview

Name	commands
Type	Resource
Id	vercel.sandboxes.commands

Fields

The following fields are returned by SELECT queries:

get

The command data along with the exit code if the command did finish.

Name	Datatype	Description
id	string	The ID of the command. (example: cmd_123a6c5209bc3778245d011443644c8d27dc2c50)
name	string	The name of the command. (example: npm)
session_id	string	The ID of the session associated with the command. (example: sbx_123a6c5209bc3778245d011443644c8d27dc2c50) (wire: sessionId)
args	array	The arguments of the command.
cwd	string	The current working directory of the command. (example: /vercel/sandbox)
duration_ms	number	Duration of the command execution in milliseconds. (wire: durationMs)
exit_code	number	If the command did finish, the exit code. (wire: exitCode)
started_at	number	When the command was started, in milliseconds since the epoch. (wire: startedAt)

list

The list of commands executed in the session.

Name	Datatype	Description
id	string	The ID of the command. (example: cmd_123a6c5209bc3778245d011443644c8d27dc2c50)
name	string	The name of the command. (example: npm)
session_id	string	The ID of the session associated with the command. (example: sbx_123a6c5209bc3778245d011443644c8d27dc2c50) (wire: sessionId)
args	array	The arguments of the command.
cwd	string	The current working directory of the command. (example: /vercel/sandbox)
duration_ms	number	Duration of the command execution in milliseconds. (wire: durationMs)
exit_code	number	If the command did finish, the exit code. (wire: exitCode)
started_at	number	When the command was started, in milliseconds since the epoch. (wire: startedAt)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	session_id, cmd_id	wait, team_id, slug	Retrieves the current status and details of a command executed in a session. Use the wait parameter to block until the command finishes execution.
list	select	session_id	team_id, slug	Retrieves a list of all commands that have been executed in a session, including their current status, exit codes, and execution times, ordered from the most recent to the oldest.
run	exec	session_id, cmdId, command	teamId, slug	Executes a shell command inside a running session. The command runs asynchronously and returns immediately with a command ID that can be used to track its progress and retrieve its output. Optionally, use the wait parameter to stream the command status until completion.
kill	exec	cmd_id, session_id, signal	teamId, slug	Sends a signal to terminate a running command in a session. The signal can be used to gracefully stop (SIGTERM) or forcefully kill (SIGKILL) the process. The command must still be running for this operation to succeed.
get_logs	exec	session_id, cmd_id	teamId, slug	Streams the output of a command in real-time using newline-delimited JSON (ND-JSON). Each entry includes the output data and stream type. Stream types include stdout, stderr, and error (for stream failures).

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
cmdId	string	The unique identifier of the command to stream logs for.
cmd_id	string	The unique identifier of the command to stream logs for.
session_id	string	The unique identifier of the session containing the command.
slug	string	The Team slug to perform the request on behalf of.
teamId	string	The Team identifier to perform the request on behalf of.
team_id	string	The Team identifier to perform the request on behalf of. (wire: teamId)
wait	string	If set to "true", the request will block until the command finishes execution. Useful for synchronously waiting for command completion.

SELECT examples

get

Retrieves the current status and details of a command executed in a session. Use the wait parameter to block until the command finishes execution.

SELECT
id,
name,
session_id,
args,
cwd,
duration_ms,
exit_code,
started_at
FROM vercel.sandboxes.commands
WHERE session_id = '{{ session_id }}' -- required
AND cmd_id = '{{ cmd_id }}' -- required
AND wait = '{{ wait }}'
AND team_id = '{{ team_id }}'
AND slug = '{{ slug }}'
;

list

Retrieves a list of all commands that have been executed in a session, including their current status, exit codes, and execution times, ordered from the most recent to the oldest.

SELECT
id,
name,
session_id,
args,
cwd,
duration_ms,
exit_code,
started_at
FROM vercel.sandboxes.commands
WHERE session_id = '{{ session_id }}' -- required
AND team_id = '{{ team_id }}'
AND slug = '{{ slug }}'
;

Lifecycle Methods

EXEC variables use wire (API) names.

run

Executes a shell command inside a running session. The command runs asynchronously and returns immediately with a command ID that can be used to track its progress and retrieve its output. Optionally, use the wait parameter to stream the command status until completion.

EXEC vercel.sandboxes.commands.run 
@session_id='{{ session_id }}' --required, 
@cmdId='{{ cmdId }}' --required, 
@teamId='{{ teamId }}', 
@slug='{{ slug }}' 
@@json=
'{
"command": "{{ command }}", 
"args": "{{ args }}", 
"cwd": "{{ cwd }}", 
"env": "{{ env }}", 
"sudo": {{ sudo }}, 
"wait": {{ wait }}, 
"logs": {{ logs }}, 
"timeout": {{ timeout }}
}'
;

kill

Sends a signal to terminate a running command in a session. The signal can be used to gracefully stop (SIGTERM) or forcefully kill (SIGKILL) the process. The command must still be running for this operation to succeed.

EXEC vercel.sandboxes.commands.kill 
@cmd_id='{{ cmd_id }}' --required, 
@session_id='{{ session_id }}' --required, 
@teamId='{{ teamId }}', 
@slug='{{ slug }}' 
@@json=
'{
"signal": {{ signal }}
}'
;

get_logs

Streams the output of a command in real-time using newline-delimited JSON (ND-JSON). Each entry includes the output data and stream type. Stream types include stdout, stderr, and error (for stream failures).

EXEC vercel.sandboxes.commands.get_logs 
@session_id='{{ session_id }}' --required, 
@cmd_id='{{ cmd_id }}' --required, 
@teamId='{{ teamId }}', 
@slug='{{ slug }}'
;