Using definition files

Airplane CLI 0.3 introduces the concept of a definition file for Airplane tasks. With the definition file, you can now:

Create new tasks with the CLI tool.
Configure settings that were previously only editable via the web UI (e.g. description, parameters, environment variables). Note: Currently folders and permissions are not editable via the CLI tool.
Configure tasks without script-based entrypoints (e.g. REST and SQL tasks).

If you haven't installed the CLI, do that before continuing.

New tasks

Airplane creates a definition file for all new tasks:

bash
Copied
1
$ airplane tasks init
2
? What should this task be called? my_task
3
? What kind of task should this be? SQL
4
? Where should the script be created? my_task.sql
5
- Created my_task.sql
6
? Where should the definition file be created? my_task.task.yaml
7
- Created my_task.task.yaml
8

9
✅ To complete your task:
10
- Add the name of a database resource to my_task.task.yaml
11
- Write your query in my_task.sql
12
- Add a description, parameters, and more details in my_task.task.yaml
13

14
🛫 To deploy your task to Airplane:
15
  airplane deploy my_task.task.yaml

This creates the task locally, including the definition file and any supporting script files. Tasks must be deployed to Airplane before other members of your team can use them.

(Deprecated) You can also create tasks without a definition file with airplane tasks init --code-only=true. However, these tasks must be created in the web UI before they can be deployed, and not all tasks can be managed without definition files.

Existing tasks

You can generate a definition file for an existing task by using the task's unique slug. For example:

bash
Copied
1
$ airplane tasks init --from my_task

If you have an existing Node, Python, or shell task, you can optionally link its existing entrypoint:

bash
Copied
1
$ airplane tasks init --from my_node_task my_task.ts

In both these cases, Airplane will generate a definition file for you (e.g., my_task.task.yaml). This definition file can live anywhere, but if your task is a Node, Python, shell, or SQL task, the specification of the entrypoint in the definition file needs to be relative to the location of the definition file. For example:

yaml
Copied
1
name: My Task
2
slug: my_task
3
node:
4
  nodeVersion: "18"
5
  entrypoint: subdir/my_task.ts # Relative to where this definition file exists

You can rerun airplane tasks init --from my_task at any time to pull down the current definition of the task. This is useful if you make changes to your tasks in the web UI and want to update your definition files.

Deploying

You can deploy your tasks by specifying definition files:

bash
Copied
1
$ airplane deploy my_task.task.yaml

You can deploy new tasks to Airplane this way; you no longer need to create the task through the web UI before deploying. If you deploy a new task, you'll be asked to confirm whether a new task should be created:

bash
Copied
1
$ airplane deploy my_task.task.yaml
2
? Task with slug my_task does not exist. Would you like to create a new task? (Y/n)

You can also specify directories when deploying. In that case, Airplane will recursively walk through them, deploying any tasks it finds. Definition files will be preferred over linked script files, if both are found.

Executing

You can execute your tasks by specifying slug or definition files. Assuming that my_task.task.yaml is linked to the task my_task, the following are equivalent:

bash
Copied
1
$ airplane execute my_task
2
$ airplane execute my_task.task.yaml

Next Steps