Prompts
Wait for a response from an operator before continuing
Airplane Prompts are currently in beta, and minor details may change. We'd love to hear any feedback
or requests at hello@airplane.dev.
Tasks can easily gather input from operators using prompts. Each prompt contains a parameter form,
similar to what you see when executing a task or runbook. When a prompt is created, a run will wait
for a response before continuing. Prompts allow you to specify reviewers with with
Approvals to build dynamic approval flows.
Example: dry runs
A common use case for prompts is to perform dry-runs. Let's look at an example:
typescriptCopied1import airplane from "airplane";23export default airplane.task(4{5slug: "task_dryrun",6},7async () => {8// Perform a dry-run and show the output to the operator with a display.9const dryRun = await airplane.execute("my_task_slug", {10dry_run: true,11});12await airplane.display.json(dryRun.output);1314// Ask the operator if we should continue.15await airplane.prompt.confirm({16description: `Review the dry-run output above. If it looks correct, click OK to apply the changes.`,17});1819// If confirmed, we can re-run:20const run = await airplane.execute("my_task_slug", {21dry_run: false,22});2324return run.output;25}26);
javascriptCopied1import airplane from "airplane";23export default airplane.task(4{5slug: "task_dryrun",6},7async () => {8// Perform a dry-run and show the output to the operator with a display.9const dryRun = await airplane.execute("my_task_slug", {10dry_run: true,11});12await airplane.display.json(dryRun.output);1314// Ask the operator if we should continue.15await airplane.prompt.confirm({16description: `Review the dry-run output above. If it looks correct, click OK to apply the changes.`,17});1819// If confirmed, we can re-run:20const run = await airplane.execute("my_task_slug", {21dry_run: false,22});2324return run.output;25}26);
pythonCopied1import airplane234@airplane.task()5def task_dryrun():6# Perform a dry-run and show the output to the operator with a display.7dry_run = airplane.execute(8"my_task_slug",9{10"dry_run": True,11},12)13airplane.display.json(dry_run.output)14# Ask the operator if we should continue.15airplane.prompt(16description=(17"Review the dry-run output above. If it looks correct, "18"click OK to apply the changes."19),20)21# If confirmed, we can re-run:22run = airplane.execute(23"my_task_slug",24{25"dry_run": False,26},27)
If you've done UNIX scripting before, you have likely seen this pattern using the
read
command --
e.g.bashCopied1# perform a dry-run...23read -p "Continue? [yN] " -n 1 -r4echo5if [[ $REPLY =~ ^[Yy]$ ]]6then7# apply!8fi
Compared to the classic shell script, prompts offer a few compelling advantages:
- Notifications: Users are automatically notified when prompted.
- Parameters: Prompts can ask for arbitrary parameters with validation.
- Slack: Prompts can be responded to directly from Slack.
Parameters
Prompt parameters support the same configuration options as task parameters e.g. default values,
descriptions, constraints, and more! See Parameters for more information
about Airplane parameters.
Short text
Creates a prompt for a short text input.

typescriptCopied1const { email } = await airplane.prompt(2// Mapping of slug -> parameter definition3{ email: "shorttext" }4);5// or6const { email } = await airplane.prompt({7// Mapping of slug -> parameter definition8email: {9type: "shorttext",10name: "Email address",11// ...12},13});
API
javascriptCopied1const { email } = await airplane.prompt(2// Mapping of slug -> parameter definition3{ email: "shorttext" }4);5// or6const { email } = await airplane.prompt({7// Mapping of slug -> parameter definition8email: {9type: "shorttext",10name: "Email address",11// ...12},13});
API
pythonCopied1values = airplane.prompt(2# Mapping of slug -> parameter definition3{"email": str}4)5# Access prompt value via values['email']67# or8values = airplane.prompt(9{10# Mapping of slug -> parameter definition11#12# More details about inline parameter configuration can be found here:13# https://docs.airplane.dev/tasks/python-config#additional-configuration14"email": Annotated[15str,16airplane.ParamConfig(17name="Email address",18# ...19),20]21},22)23# Access prompt value via values['email']
API
Long text
Creates a prompt for a long text input that renders as a
multi-line text area.

typescriptCopied1const { reason } = await airplane.prompt(2// Mapping of slug -> parameter definition3{ reason: "longtext" }4);5// or6const { reason } = await airplane.prompt({7// Mapping of slug -> parameter definition8reason: {9type: "longtext",10name: "Refund reason",11// ...12},13});
API
typescriptCopied1const { reason } = await airplane.prompt(2// Mapping of slug -> parameter definition3{ reason: "longtext" }4);5// or6const { reason } = await airplane.prompt({7// Mapping of slug -> parameter definition8reason: {9type: "longtext",10name: "Refund reason",11// ...12},13});
API
pythonCopied1values = airplane.prompt(2# Mapping of slug -> parameter definition3{"reason": airplane.LongText}4)5# Access prompt value via values['reason']67# or8values = airplane.prompt(9{10# Mapping of slug -> parameter definition11#12# More details about inline parameter configuration can be found here:13# https://docs.airplane.dev/tasks/python-config#additional-configuration14"reason": Annotated[15airplane.LongText,16airplane.ParamConfig(17name="Refund reason",18# ...19),20]21},22)23# Access prompt value via values['reason']
API
SQL
Creates a prompt for a SQL input that renders within a code editor with
SQL syntax highlighting.

typescriptCopied1const { query } = await airplane.prompt(2// Mapping of slug -> parameter definition3{ query: "sql" }4);5// or6const { query } = await airplane.prompt({7// Mapping of slug -> parameter definition8query: {9type: "sql",10name: "SQL query",11// ...12},13});
API
javascriptCopied1const { query } = await airplane.prompt(2// Mapping of slug -> parameter definition3{ query: "sql" }4);5// or6const { query } = await airplane.prompt({7// Mapping of slug -> parameter definition8query: {9type: "sql",10name: "SQL query",11// ...12},13});
API
pythonCopied1values = airplane.prompt(2# Mapping of slug -> parameter definition3{"query": airplane.SQL}4)5# Access prompt value via values['query']67# or8values = airplane.prompt(9{10# Mapping of slug -> parameter definition11#12# More details about inline parameter configuration can be found here:13# https://docs.airplane.dev/tasks/python-config#additional-configuration14"query": Annotated[15airplane.SQL,16airplane.ParamConfig(17name="SQL query",18# ...19),20]21},22)23# Access prompt value via values['query']
API
Number
Creates a prompt for a floating point number input.

typescriptCopied1const { cost } = await airplane.prompt(2// Mapping of slug -> parameter definition3{ cost: "float" }4);5// or6const { cost } = await airplane.prompt({7// Mapping of slug -> parameter definition8cost: {9type: "float",10name: "Amount to charge",11// ...12},13});
API
javascriptCopied1const { cost } = await airplane.prompt(2// Mapping of slug -> parameter definition3{ cost: "float" }4);5// or6const { cost } = await airplane.prompt({7// Mapping of slug -> parameter definition8cost: {9type: "float",10name: "Amount to charge",11// ...12},13});
API
pythonCopied1values = airplane.prompt(2# Mapping of slug -> parameter definition3{"cost": float}4)5# Access prompt value via values['cost']67# or8values = airplane.prompt(9{10# Mapping of slug -> parameter definition11#12# More details about inline parameter configuration can be found here:13# https://docs.airplane.dev/tasks/python-config#additional-configuration14"cost": Annotated[15float,16airplane.ParamConfig(17name="Amount to charge",18# ...19),20]21},22)23# Access prompt value via values['cost']
API
Integer
Creates a prompt for an integer input.

typescriptCopied1const { count } = await airplane.prompt(2// Mapping of slug -> parameter definition3{ count: "integer" }4);5// or6const { count } = await airplane.prompt({7// Mapping of slug -> parameter definition8count: {9type: "integer",10name: "Record count",11// ...12},13});
API
javascriptCopied1const { count } = await airplane.prompt(2// Mapping of slug -> parameter definition3{ count: "integer" }4);5// or6const { count } = await airplane.prompt({7// Mapping of slug -> parameter definition8count: {9type: "integer",10name: "Record count",11// ...12},13});
API
pythonCopied1values = airplane.prompt(2# Mapping of slug -> parameter definition3{"count": int}4)5# Access prompt value via values['count']67# or8values = airplane.prompt(9{10# Mapping of slug -> parameter definition11#12# More details about inline parameter configuration can be found here:13# https://docs.airplane.dev/tasks/python-config#additional-configuration14"count": Annotated[15int,16airplane.ParamConfig(17name="Record count",18# ...19),20]21},22)23# Access prompt value via values['count']
API
Boolean
Creates a prompt for a boolean input.

typescriptCopied1const { ok } = await airplane.prompt(2// Mapping of slug -> parameter definition3{ ok: "boolean" }4);5// or6const { ok } = await airplane.prompt({7// Mapping of slug -> parameter definition8ok: {9type: "boolean",10name: "Countinue",11// ...12},13});
API
javascriptCopied1const { ok } = await airplane.prompt(2// Mapping of slug -> parameter definition3{ ok: "boolean" }4);5// or6const { ok } = await airplane.prompt({7// Mapping of slug -> parameter definition8ok: {9type: "boolean",10name: "Countinue",11// ...12},13});
API
pythonCopied1values = airplane.prompt(2# Mapping of slug -> parameter definition3{"reason": airplane.LongText}4)5# Access prompt value via values['reason']67# or8values = airplane.prompt(9{10# Mapping of slug -> parameter definition11#12# More details about inline parameter configuration can be found here:13# https://docs.airplane.dev/tasks/python-config#additional-configuration14"reason": Annotated[15airplane.LongText,16airplane.ParamConfig(17name="Refund reason",18# ...19),20]21},22)23# Access prompt value via values['reason']
API
Date
Creates a prompt for a date input. Dates identify a day of the year and
do not include a time component. If you need that, see Datetime.

typescriptCopied1const { date } = await airplane.prompt(2// Mapping of slug -> parameter definition3{ date: "date" }4);5// or6const { date } = await airplane.prompt({7// Mapping of slug -> parameter definition8date: {9type: "date",10name: "Start date",11// ...12},13});
API
javascriptCopied1const { date } = await airplane.prompt(2// Mapping of slug -> parameter definition3{ date: "date" }4);5// or6const { date } = await airplane.prompt({7// Mapping of slug -> parameter definition8date: {9type: "date",10name: "Start date",11// ...12},13});
API
pythonCopied1values = airplane.prompt(2# Mapping of slug -> parameter definition3{"date": datetime.date}4)5# Access prompt value via values['date']67# or8values = airplane.prompt(9{10# Mapping of slug -> parameter definition11#12# More details about inline parameter configuration can be found here:13# https://docs.airplane.dev/tasks/python-config#additional-configuration14"date": Annotated[15datetime.date,16airplane.ParamConfig(17name="Start date",18# ...19),20]21},22)23# Access prompt value via values['date']
API
Datetime

typescriptCopied1const { timestamp } = await airplane.prompt(2// Mapping of slug -> parameter definition3{ timestamp: "datetime" }4);5// or6const { timestamp } = await airplane.prompt({7// Mapping of slug -> parameter definition8timestamp: {9type: "datetime",10name: "Incident start",11// ...12},13});
API
javascriptCopied1const { timestamp } = await airplane.prompt(2// Mapping of slug -> parameter definition3{ timestamp: "datetime" }4);5// or6const { timestamp } = await airplane.prompt({7// Mapping of slug -> parameter definition8timestamp: {9type: "datetime",10name: "Incident start",11// ...12},13});
API
pythonCopied1values = airplane.prompt(2# Mapping of slug -> parameter definition3{"timestamp": datetime.datetime}4)5# Access prompt value via values['timestamp']67# or8values = airplane.prompt(9{10# Mapping of slug -> parameter definition11#12# More details about inline parameter configuration can be found here:13# https://docs.airplane.dev/tasks/python-config#additional-configuration14"timestamp": Annotated[15datetime.datetime,16airplane.ParamConfig(17name="Incident start",18# ...19),20]21},22)23# Access prompt value via values['timestamp']
API
File
Support for prompts with file parameters is coming soon.
Config variables
Support for prompts with Config variables parameters is coming soon.
Examples
Multi-parameter forms
Create a multi-parameter form by specifying more than one parameter.

typescriptCopied1const {amount, reason} = await airplane.prompt(2// Mapping of slug -> parameter definition3{ reason: "shorttext" }4{ amount: "number" }5);6// or7const {amount, reason} = await airplane.prompt({8// Mapping of slug -> parameter definition9reason: {10type: "shorttext",11name: "Refund reason",12// ...13},14amount: {15type: "float",16name: "Refund amount",17// ...18},19});
API
javascriptCopied1const {amount, reason} = await airplane.prompt(2// Mapping of slug -> parameter definition3{ reason: "shorttext" }4{ amount: "number" }5);6// or7const {amount, reason} = await airplane.prompt({8// Mapping of slug -> parameter definition9reason: {10type: "shorttext",11name: "Refund reason",12// ...13},14amount: {15type: "float",16name: "Refund amount",17// ...18},19});
API
pythonCopied1values = airplane.prompt(2# Mapping of slug -> parameter definition3{"reason": str}4{"amount": float}5)6# Access prompt value via values['reason'], values['amount']78# or9values = airplane.prompt(10{11# Mapping of slug -> parameter definition12#13# More details about inline parameter configuration can be found here:14# https://docs.airplane.dev/tasks/python-config#additional-configuration15"reason": Annotated[16str,17airplane.ParamConfig(18name="Refund reason",19# ...20),21],22"amount": Annotated[23float,24airplane.ParamConfig(25name="Refund amount",26# ...27),28],29},30)31# Access prompt value via values['reason'], values['amount']
API
Confirmation
Create a prompt that has no parameters to ask users for confirmation.

typescriptCopied1// Convenience helper for prompts with no parameters2await airplane.prompt.confirm({ description: "## Please review run before continuing." });34// Equivalent to5await airplane.prompt({}, { description: "## Please review run before continuing." });
API
javascriptCopied1// Convenience helper for prompts with no parameters2await airplane.prompt.confirm({ description: "## Please review run before continuing." });34// Equivalent to this5await airplane.prompt({}, { description: "## Please review run before continuing." });
API
pythonCopied1airplane.prompt(description="## Please review run before continuing.")
API
Select options
Create a prompt for selecting a value from a list of options. Accepts values numbers, strings,
booleans, and objects.

typescriptCopied1const users = [2{ name: "Colin", id: "usr1" },3{ name: "Lee", id: "usr2" },4];5const user = await airplane.prompt.select("User", users, {6optionToLabel: (user) => user.name,7});
API
javascriptCopied1const users = [2{ name: "Colin", id: "usr1" },3{ name: "Lee", id: "usr2" },4];5const user = await airplane.prompt.select("User", users, {6optionToLabel: (user) => user.name,7});
API
Background prompts
Prompts can be created in the background via
prompt.background
. When used in combination with the
Submit Prompt API endpoint, you are able to able to programatically
submit prompts from outside of Airplane's runtime.typescriptCopied1// Create a prompt in the background to get an ID.2const myPrompt = await airplane.prompt.background({ deploy_succeeded: "boolean" });34// Start a downstream processes and pass a reference to the prompt via its ID.5await airplane.rest.request("deploy_resource", "POST", "/startDeploy", {6body: { promptID: myPrompt.promptID },7});89// In this case, the request from the downstream processes would look like10// curl https://api.airplane.dev/v0/prompts/submit \11// -X POST \12// -H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \13// -d '{14// "id": "pmt20221122zyydx3rho2t",15// "values": {16// "deploy_succeeded": "true",17// }18//}'1920// Wait on the downstream process to submit the prompt via the Airplane API.21const { deploy_succeeded } = await myPrompt.wait();
API
javascriptCopied1// Create a prompt in the background to get an ID.2const myPrompt = await airplane.prompt.background({ deploy_succeeded: "boolean" });34// Start a downstream processes and pass a reference to the prompt via its ID.5await airplane.rest.request("deploy_resource", "POST", "/startDeploy", {6body: { promptID: myPrompt.promptID },7});89// In this case, the request from the downstream processes would look like10// curl https://api.airplane.dev/v0/prompts/submit \11// -X POST \12// -H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \13// -d '{14// "id": "pmt20221122zyydx3rho2t",15// "values": {16// "deploy_succeeded": "true",17// }18//}'1920// Wait on the downstream process to submit the prompt via the Airplane API.21const { deploy_succeeded } = await myPrompt.wait();
API
pythonCopied1# Create a prompt in the background to get an ID.2my_prompt = airplane.prompt({"deploy_succeeded": bool}, background=True)34# Start a downstream processes and pass a reference to the prompt via its ID.5airplane.rest.request(6"deployResource",7"POST",8"/startDeploy",9body={"promptID": my_prompt.prompt_id},10)1112# In this case, the request from the downstream processes would look like13# curl https://api.airplane.dev/v0/prompts/submit \14# -X POST \15# -H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \16# -d '{17# "id": "pmt20221122zyydx3rho2t",18# "values": {19# "deploy_succeeded": "true",20# }21# }'2223# Wait on the downstream process to submit the prompt via the prompts submit endpoint.24values = my_prompt.wait()
API