This article explains how to create and run commands in the Swif Web App that:

Run by Command Script
Run by OSQuery
Run by File
Pull code from a Git repository
Work consistently across Mac, Windows, and Linux devices

1. Overview of Execution Types

When you create a new command in Swif Web App, you’ll now see three main ways to provide your script:

Run by Command Script
- Paste or write a command/script directly in the UI.
- Best for simple, one-off commands or short scripts.
Run by OSQuery
1. Run SQL‑style queries against devices (Mac, Windows, and Linux) and
2. View the results in a structured table, without writing any custom parsing or UI.
Run by File
- Paste the entire file contents (e.g. main.py, script.js, main.go, test.sh).
- Swif saves and runs it as that file on the device.
- Best when you have a single file and don’t need Git or a repo structure.
Run by Git Repo (Git)
- Point Swif at a Git repository.
- Swif clones the repo and runs an executable file.
- Best for production/CI-like workflows, multi-file projects, and reusable automation.

Note: Existing “custom command” shell-script functionality becomes Run by Command Script, and remains unchanged. The new options are additive.

2. Accessing Command Creation

Sign in to the Swif Web App.
Navigate to your Commands section.
Click Create new command.

You’ll land on a multi-step flow. The first step now groups fields into:

Basic Information
Execution Type
Execution Settings

3. Run by Command Script (Quick Recap)

When you select Run by Command Script as the Script Source:

You’ll see fields for:
- Command name, description
- The script/command to run
- Scheduling and status options
- Optional webhook configuration (if available)
You’ll also see a Run Security Risk Analysis button, which lets you analyze the risk profile of the command before saving.

Review page:

Use this when you need a quick, direct command without external files or Git.

Learn more at Run by Command Script.

4. Run by OSQuery

Swif supports running OSQuery commands as a specialized command type. This lets you run SQL‑style queries against devices (Mac, Windows, and Linux) and view the results in a structured table, without writing any custom parsing or UI.

OSQuery commands are most useful when you want to:

Collect detailed inventory or configuration data from devices.
Audit specific apps, extensions, or security posture across your fleet.
Re‑use a standard query as a template for future runs.

4.1 Run by OSQuery Command

You can create reusable OSQuery command templates in the Swif Web App.

Go to Commands.
Choose Run by OSQuery as the command type.

For OSQuery templates:

Execution Type is:
- Pre‑configured with the OSQuery script behavior.
- Read‑only / disabled (you don’t pick Script/File/Git here).
You fill out the rest of the template details (name, scope, etc.) as usual.
Once saved, the template appears in the templates list with its Execution Type shown as OSQuery.

You can then use this template to create and run OSQuery commands across Mac, Windows, and Linux devices.

4.2 Running an OSQuery Command

When you run an OSQuery command (e.g., from a template or directly):

Swif sends the OSQuery SQL to the device.
The device’s OSQuery agent executes the query.
The results are returned to Swif and stored so you can review them in a Command Report.

For OSQuery commands specifically:

Timeout After and Run As fields are not required and are hidden in the creation/update flow.
The command is clearly labeled as an OSQuery command in the Commands list and Command Details.

Note: The content and columns in the result depend entirely on the OSQuery SQL you use. Different queries can return different sets of columns.

4.3 Viewing OSQuery Command Reports

OSQuery results are displayed as a structured, readable table instead of a raw text block.

You can open the OSQuery Command Report in two ways:

From Command Details
- Go to Commands.
- Open an OSQuery command.
- Click Command Report.
- You’ll see a table view of all returned rows and columns for that command.
From Device Details
- Go to Devices → [Select a device] → Commands tab.
- Find the OSQuery command in the list.
- Click View report.
- The same OSQuery Command Report opens for that specific device/command.

Both entry points show the same underlying data; the view is consistent between Commands and Device Details.

4.4 Dynamic Columns and Column Selection

Because OSQuery queries are fully customizable:

The columns in the report are dynamic.
Swif does not hard‑code any specific column set.
Whatever columns OSQuery returns are displayed as table columns in the report.

To help you focus on the data that matters:

You can use a column selector in the report to show/hide columns.
Sorting and filtering on OSQuery reports are not available today, to keep the UI compatible with any possible OSQuery schema.

Example: VS Code Extensions
If you use an OSQuery script that returns VS Code extensions, you may see columns like:

name
version
bundle_identifier
extension_id
browser
source
vendor
last_opened_at
installed_path

These will appear automatically if the query includes them—no extra configuration needed.

4.5 Downloading OSQuery Results

From the OSQuery Command Report you can:

Download the result set as a CSV file.

The CSV includes the same dynamic columns and rows you see in the report at the time of download, making it easy to:

Share results with other teams.
Import into spreadsheets or external analytics tools.
Archive audit results.

5. Run by File

When you choose Run by File as the Execution Type:

5.1 What Run by File Does

You provide:
- Filename (e.g. main.py, main.go, test.sh)
- File content (the exact script content)
Swif saves this file on the target device with the filename you specify and then runs it.

Important:
If you only provide a build or run command (e.g. python main.py) but do not supply the file and filename, the agent would have to store a randomly named file, which breaks references like python main.py. That’s why an exact filename is required.

5.2 When Run Schedule & Webhooks Are Hidden

For Run by File:

Webhook configuration is not available for Run by File commands.

This is intentional: Run by File is optimized for simpler executions, not long-lived scheduled jobs or webhook-driven pipelines.

5.3 Review Step

The Review page for Run by File shows:
- Command name and description
- Target platforms/devices
- Filename and summary of file contents

Use Run by File when you have a single script file and want a straightforward way to execute it without Git.

6. Run by Git Repo

When you select Run by Git Repo as the Execution Type:

6.1 What Run by Git Repo Does

You configure a Git repository as the script source.
Swif:
1. Clones the repository to the device or runner.
2. Execute the specified Build script.
This works across Mac, Windows, and Linux, using a consistent UX.

6.2 Fields You’ll Configure

Typical fields in the Run by Git Repo flow include:

Repository provider & URL
- For example: GitHub, GitLab, or another Git provider and the HTTPS/SSH URL.
Branch
- The branch to clone and run from (e.g. main, develop).
Path to Build script
- If your build script is not at the repo root, specify the path (e.g. ./scripts/deploy).

These fields are wired to backend capabilities for:

Storing your Git repo configuration.
Triggering to run the Build script.
Returning status, logs, and errors.

6.3 What’s Hidden for Run by Git

For Run by Git Repo:

Webhook configuration is not available.

This keeps the UX focused on Git + execution itself.

6.4 Review Page

The Review step for Run by Git Repo shows:

Repo details:
- Provider (e.g., GitHub)
- Repo URL
- Branch
Build script:
- Where Swif will run the Build script from
- Which target will be executed
Any platform-specific execution settings (timeouts, environment, etc.), if applicable.

7. Platform Behavior (Mac, Windows, Linux)

The Web App UX is designed to be consistent across all three OS platforms, while allowing for platform-specific constraints to be surfaced.

7.1 macOS

Supports Run by Custom script, Run by File, or by Git repo.
UI surfaces any Mac-specific notes, such as:
- Runner availability
- Permission requirements
- Path patterns or shell expectations (e.g., POSIX paths)

7.2 Windows

Provides an equivalent UX for creating and reviewing commands.
The Web App keeps the same fields and validation behavior as Mac, but:
- May surface Windows-specific guidance, such as:
  - Path format differences
  - Shell constraints (e.g. PowerShell vs Bash in your environment)
Goal: You configure once with a familiar layout, and only care about platform differences where strictly necessary.

7.3 Linux

Offers the same command-creation flow for Linux devices.
Any Linux-specific constraints are surfaced, such as:
- Supported distributions
- Required packages or tooling
- Runner prerequisites

Across all three, the core behavior & UX remain aligned, so you don’t need to learn a separate workflow per OS.

8. Execution, Status, and Logs in the Web App

Once you’ve created a Run by Git Repo command:

Trigger or schedule execution from the Web App.
The Web App:
- Dispatches the job to the selected platform(s).
- Uses the Build script runner with your configured repo, path, and target.
You can then:
- View execution status in the command/job detail view.
- Access logs and errors from the same UI you already use for other commands.

8.1 Error Handling

The Web App surfaces user-friendly errors for Command reports, including cases like:

Script error
Repository unreachable or inaccessible (auth issues, network, wrong URL).
Branch not found.
Build script not found at the given path.

Errors are displayed in the existing command/job detail UI, using the same patterns as other runners where possible.

9. Validation and Acceptance Criteria (What “Working” Looks Like)

When this feature is working as intended:

You can create a command for Mac, Windows, or Linux that:
- Uses a Run by Custom script;
- Uses a Run by File script;
- Uses a Git repository as its script source.
All configuration fields validate correctly:
- For the Custom script, the required script and arguments
- For the Run by File, the required file name and script
- For the Run by Git repo, the required repo URL, branch, path, and target fields are present.
- Missing or invalid values are clearly highlighted with error messages.
The Review step clearly displays:
- Repo provider, URL, branch.
- Path and target for Run by Git Repo
- Any platform-specific settings are configured.
When you run the command:
- You see the execution status.
- Logs and error messages appear in the usual command/job detail UI.

10. Choosing Between Script, File, and Git

Use this quick guide to pick the right option:

Run by Command Script
- For quick, simple commands, you type directly.
- Example: sudo softwareupdate -i -a on macOS.
Run by File
- For a single script file you manage in Swif.
- You need to name the file exactly as it’s referenced in your command (e.g., python main.py requires main.py to exist).
Run by Git Repo
- For reusable, structured automations maintained in Git.
- Builds, deployments, tests, and complex workflows that rely on a full repo and build script targets.