Skip to main content

​
Command Syntax

symphony [OPTIONS] [WORKFLOW_PATH]

​
Arguments

​
WORKFLOW_PATH
string
Path to the workflow definition file. If not provided, Symphony looks for WORKFLOW.md in the current directory.The path will be expanded to an absolute path automatically.Example:
symphony --i-understand-that-this-will-be-running-without-the-usual-guardrails ./workflows/production.md

​
Options

​
Required Flag

​
--i-understand-that-this-will-be-running-without-the-usual-guardrails
boolean
required
Acknowledgement flag that must be provided to run Symphony.This flag confirms that you understand:
  • Symphony is an engineering preview
  • Codex will run without guardrails
  • SymphonyElixir is not a supported product
Without this flag, Symphony will display an acknowledgement banner and exit with code 1.
Example:
symphony --i-understand-that-this-will-be-running-without-the-usual-guardrails

​
Configuration Flags

​
--logs-root
string
Sets the root directory for Symphony log files.The path will be expanded to an absolute path and trimmed of whitespace. Empty strings are not allowed.This configures the :log_file application environment variable for :symphony_elixir.
symphony --logs-root ./logs --i-understand-that-this-will-be-running-without-the-usual-guardrails
If --logs-root is provided multiple times, the last value wins.
​
--port
integer
Overrides the default server port for the Symphony HTTP server.Must be a non-negative integer (0-65535). The value is validated before being set.This configures the :server_port_override application environment variable for :symphony_elixir.
symphony --port 4000 --i-understand-that-this-will-be-running-without-the-usual-guardrails
If --port is provided multiple times, the last value wins.

​
Usage Examples

​
Default Workflow

Run with WORKFLOW.md in the current directory: 
symphony --i-understand-that-this-will-be-running-without-the-usual-guardrails

​
Custom Workflow File

Run with a specific workflow file: 
symphony --i-understand-that-this-will-be-running-without-the-usual-guardrails ./workflows/staging.md

​
Full Configuration

Combine all options: 
symphony \
  --logs-root /var/log/symphony \
  --port 4000 \
  --i-understand-that-this-will-be-running-without-the-usual-guardrails \
  ./workflows/production.md

​
Error Handling

​
Missing Acknowledgement Flag

If you forget the required acknowledgement flag: 
symphony ./workflows/production.md
Symphony displays a warning banner and exits: 
╭────────────────────────────────────────────────────────────────────────────╮
│                                                                            │
│ This Symphony implementation is a low key engineering preview.             │
│ Codex will run without any guardrails.                                     │
│ SymphonyElixir is not a supported product and is presented as-is.          │
│ To proceed, start with `--i-understand-that-this-will-be-running-without-  │
│ the-usual-guardrails` CLI argument                                         │
│                                                                            │
╰────────────────────────────────────────────────────────────────────────────╯

​
Workflow File Not Found

If the specified workflow file doesn’t exist: 
symphony --i-understand-that-this-will-be-running-without-the-usual-guardrails ./missing.md
Error output: 
Workflow file not found: /absolute/path/to/missing.md
Exit code: 1

​
Invalid Usage

If you provide invalid arguments: 
symphony --invalid-flag --i-understand-that-this-will-be-running-without-the-usual-guardrails
Error output: 
Usage: symphony [--logs-root <path>] [--port <port>] [path-to-WORKFLOW.md]
Exit code: 1

​
Application Start Failure

If Symphony fails to start: 
Failed to start Symphony with workflow /path/to/WORKFLOW.md: <reason>
Exit code: 1

​
Exit Codes

​
0
exit code
Normal shutdown - Symphony supervisor terminated successfully
​
1
exit code
Error occurred:
  • Missing required acknowledgement flag
  • Workflow file not found
  • Invalid command-line arguments
  • Application failed to start
  • Supervisor crashed or terminated abnormally

​
Implementation Details

​
Option Parsing

Symphony uses strict option parsing with the following switches: 
@switches [
  {:i_understand_that_this_will_be_running_without_the_usual_guardrails, :boolean},
  logs_root: :string,
  port: :integer
]

​
Workflow Path Expansion

The workflow path is expanded using Path.expand/1 before validation:
  • Relative paths are resolved from the current working directory
  • ~ is expanded to the user’s home directory
  • The expanded path must point to a regular file

​
Configuration Application

CLI options configure the Elixir application environment:
CLI FlagApplication ConfigModule
--logs-root:symphony_elixir, :log_fileSymphonyElixir.LogFile
--port:symphony_elixir, :server_port_overrideSymphonyElixir.CLI
Workflow pathSet via SymphonyElixir.WorkflowSymphonyElixir.Workflow

​
Process Lifecycle

After successful startup:
  1. Symphony monitors the SymphonyElixir.Supervisor process
  2. Waits for the supervisor to terminate
  3. Exits with appropriate code based on termination reason:
    • :normal → exit code 0
    • Any other reason → exit code 1

Build docs developers (and LLMs) love

Get started for freeTalk to us