# How to trigger AFT! jobs from the command line

AFT! provides two commands for running scripts from a shell or a CI/CD pipeline.

<table border="1" id="bkmrk-command-what-it-does" style="border-collapse: collapse; width: 100%; height: 89.3907px;"><colgroup><col style="width: 20.6548%;"></col><col style="width: 79.4644%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Command**</td><td style="height: 29.7969px;">**What it does**</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">`aft start`</td><td style="height: 29.7969px;">Calls the REST API of a running AFT! instance and queues the job there. The script runs inside the service, with full access to the VFS Library and secrets. Returns immediately; the job runs in the background.</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">`aft run`</td><td style="height: 29.7969px;">Executes a `.syncjs` file directly in the calling shell process. No API key needed. The script runs to completion before the command returns.</td></tr></tbody></table>

#### `aft start`: trigger a stored script via API

##### Prerequisite

Create an API key in the AFT! web UI under Settings &gt; API Keys. Make sure the key's IP allowlist includes the machine you will be calling from. For calls from the same machine, 127.0.0.1 is sufficient.

[![image.png](https://kb.syncplify.com/uploads/images/gallery/2026-04/scaled-1680-/image.png)](https://kb.syncplify.com/uploads/images/gallery/2026-04/image.png)

##### Minimal example

Linux/MacOS:

```bash
./aft start -n "My Backup Job" -a "xiM2ruBm2QZkhTSN6BPd9BqmxVEBVbrgNYVMkNQb6hfj"
```

Windows (PowerShell):

```powershell
.\aft.exe start -n "My Backup Job" -a "xiM2ruBm2QZkhTSN6BPd9BqmxVEBVbrgNYVMkNQb6hfj"
```

Script names are matched case-insensitively.

##### With parameters and a remote instance

Linux/MacOS:

```bash
aft start \
  -n "My Backup Job" \
  -a "xiM2ruBm2QZkhTSN6BPd9BqmxVEBVbrgNYVMkNQb6hfj" \
  --params '{"character":"goofy"}' \
  --host "192.168.1.10:44399"
```

Windows (PowerShell):

```powershell
.\aft.exe start `
  -n "My Backup Job" `
  -a "xiM2ruBm2QZkhTSN6BPd9BqmxVEBVbrgNYVMkNQb6hfj" `
  --params '{"character":"goofy"}' `
  --host "192.168.1.10:44399"
```

Inside the script, read the parameter with `Param("character")`.

`--host` defaults to `127.0.0.1:44399` when omitted.

#### `aft run`: execute a script file directly

The ***Allow CLI Run*** option must be enabled in AFT! Settings. It is **disabled by default** but an administrator can enable it.

##### Minimal example

Linux/MacOS:

```bash
./aft run -f "/opt/scripts/my-transfer.syncjs"
```

Windows (PowerShell):

```powershell
.\aft.exe run -f "C:\Scripts\my-transfer.syncjs"
```

##### With parameters

Linux/MacOS:

```bash
./aft run -f "/opt/scripts/my-transfer.syncjs" -p '{"destination":"/archive/2026"}'
```

Windows (PowerShell):

```powershell
.\aft.exe run -f "C:\Scripts\my-transfer.syncjs" -p '{"destination":"D:\Archive\2026"}'
```

##### Notes

- `aft run` executes **synchronously**: the command blocks until the script finishes and exits with code 0 on success, or code 1 if the script crashes or fails.
- If `aft serve` is running on the same machine, `aft run` automatically delegates to the running service so the script has full access to the VFS Library and secrets. If `aft serve` is not running, it opens the local database directly.
- This makes aft run a natural fit for OS-cron jobs, CI/CD pipelines, and shell scripts that need a definitive exit code.