Skip to content

SØAD CLI

SØAD CLI is a client for SØAD that allows you to manage your SØAD projects easily. It provides commands to pull and push transactions from the SØAD Server. By using the CLI, you get the ability to edit your transactions locally using your favorite editor and then push the changes back to the SØAD Server. You can pull single transaction or all transactions from the Server but you can push only single transaction to the Server.

By using this CLI, you can leverage the full power of your local editor, such as Visual Studio Code, along with its extensions and features. This allows you to edit transactions with advanced tools like syntax highlighting, linting, and version control integration, ensuring a seamless and efficient development experience.

Installation

To install the SØAD CLI, you can download the latest release from the SØAD CLI GitHub repository. After downloading, extract the contents and add the soad executable to your system's PATH.

Configuration

The CLI stores credentials and settings in .config.json in the current directory. It supports:

  • Encrypted token storage (with passphrase)
  • Multiple project folders with isolated config

Usage

To use the SØAD CLI, open your terminal and run the following command:

soad [command] [options]

~ ❯ soad --help
A CLI for SØAD Online IDE

Usage:
  soad [command]

Available Commands:
  changed     List transactions that have local changes
  clean       Delete all files in the src directory
  compare     Compare local and server version using Meld
  completion  Generate the autocompletion script for the specified shell
  config      Manage CLI configuration
  create      Create a new transaction remotely and pull it locally
  delete      Delete a transaction from the server and local copy
  deploy      Copy local source code to deployment folder using original SØAD structure
  help        Help about any command
  list        List available transactions
  login       Authenticate and save token
  pull        Pull one or all transactions from the SØAD server
  push        Push a transaction to the SØAD server
  push-all    Push all locally changed transactions (safely)
  push-remote Push selected transactions to another SØAD server with a specific version
  release     Create a new release snapshot on remote server
  rollback    Rollback server to a specific release version

Flags:
  -h, --help            help for soad
      --insecure        Allow insecure server connections when using SSL
      --server string   Base URL of SØAD Server (default "http://localhost:8080")

Use "soad [command] --help" for more information about a command.

Commands

login

Login to SØAD Server. You need to login first before you can run any command.

soad login [options]

Options

  • --server: Set the server's URL (e.g. https://playground.sufia.online). This option is required.

pull

Pulls transactions from the SØAD Server to your local machine.

soad pull [options]

Options

  • --all: Pull all transactions from the server.
  • --group <group_name> --code <transaction_code>: Pull a specific transaction by its group and code.

push

Pushes a transaction from your local machine to the SØAD Server.

soad push [options]

Options

  • --group <group_name> --code <transaction_code>: Specify the group and code of the transaction.

compare

Compare the local version of a transaction with the server version using Meld by default. You can change the comparison tool by setting the diff_tool parameter in the CLI configuration. If Meld or your preferred tool is not in your system PATH, specify its full path in the diff_tool setting.

soad compare [options]

Options

  • --group <group_name> --code <transaction_code>: Specify the group and code of the transaction to compare.

Example

soad compare --group <group_name> --code <transaction_code>

# Set the diff tool to use for comparison (e.g., Meld)
soad config set diff_tool "/path/to/meld"

# Set the diff tool to use for comparison (e.g., Visual Studio Code)
soad config set diff_tool "code --diff"

help

Get help for a specific command.

soad [command] --help

Options

  • command: The specific command you want help with (e.g., pull, push).

Examples

  • Pull all transactions: 
    soad pull --all
soad pull <group_name>/*
  • Pull a specific transaction: 
    soad pull --group <group_name> --code <transaction_code>
soad pull <group_name>/<transaction_code>
  • Push a transaction to the server: 
    soad push --group <group_name> --code <transaction_code>
soad push <group_name>/<transaction_code>

Deployment & Releases

# Create a new release
soad release --version "v1.0" --notes "Initial release"

# Rollback to a specific release version or 
# latest release if no version is specified
soad rollback --version "v1.0"

# List all releases
soad release --list
  • Releases are snapshots of your transactions, allowing you to manage versions and rollbacks effectively.
  • Releases are saved server-side with metadata and checksums.
  • Rollback restores all transactions to a named release version.

Note

Occasionally, pushing a transaction might fail due to security restrictions such as those enforced by a Web Application Firewall (WAF). If this happens, try using the --zip option when pushing. This will compress the transaction into a zip file before uploading, which can help bypass WAF limitations. Using zip option might be faster sometimes, especially for larger transactions.