Skip to content

Command line syntax

This page is about the command line syntax used in places like PreRunScripts and PostRunScripts.

If you are a long-time Windows power user, you may be familiar with the command line syntax used by the Windows Command Prompt (referred to as cmd from here on).

However, most operating systems, including Linux, macOS, and Android, follow the POSIX standard for command line syntax. Autory uses POSIX command line syntax.

Windows also has PowerShell, which introduces yet another command line syntax, which is out of scope for this discussion.

Notable differences between cmd and POSIX command line syntax

Slashes

POSIX uses backslashes (\) as escape characters and forward slashes (/) as path separators. For example, foo\ bar represents a single argument foo bar with a space in it, rather than two arguments foo and bar. In contrast, foo/bar represents a path to a file or directory named bar inside a directory named foo.

cmd uses backslashes (\) as path separators by default, but also supports forward slashes (/), except when referencing network paths like \\server\share.

Using forward slashes (/) as path separators might seem strange to Windows users at first, but notice that URLs on the internet also use forward slashes (/) as path separators.

Recommendation

Use forward slashes (/) as path separators for maximum compatibility across operating systems.

Quotes

Both cmd and POSIX use double quotes (") to group arguments containing spaces. However, POSIX also supports single quotes ('), which treat everything inside as literal characters, while cmd does not have this feature. Single quotes are useful when you want to include special characters (like $ or ") in an argument.

Recommendation

Use double quotes, unless you need single quotes.

File paths with spaces

With POSIX, you have multiple options to represent file paths with spaces:

  • Escape spaces with backslashes (\): My\ Documents/My\ Autory\ Model.xlsm
  • Enclose the entire path in single quotes ('): 'My Documents/My Autory Model.xlsm'
  • Enclose the entire path in double quotes ("): "My Documents/My Autory Model.xlsm"

With cmd, you have fewer options:

  • Enclose the entire path in double quotes ("): "My Documents\My Autory Model.xlsm"
  • Escape spaces with carets (^): My^ Documents\My^ Autory^ Model.xlsm

Recommendation

Use double-quotes around file paths that may contain spaces for maximum compatibility across operating systems.

Command line options

Windows tools often use forward slashes (/) to denote command line options (also called flags or switches).

Most tools on POSIX-based systems use a single hyphen for short options (like -h), and a double hyphen for long options (like --help).

This is purely by convention, and many command line tools on both systems support both styles. For command line options, you should use whatever style is appropriate for the specific tool you are using. The autory command line tool supports only hyphen-style options like -h and --help.

Recommendation

Use hyphen-style options (like -h and --help) unless the tool you are using only supports slash-style options.

Why Autory uses POSIX command line syntax.

  • It's portable across operating systems.
  • It's more consistent and predictable.
  • It's more widely adopted.
  • It's easier to implement and integrate with other tools, like Python's subprocess.run.

What Autory does to handle these differences

When running Autory on Windows, we check if the provided commands would be interpreted differently in cmd vs. POSIX. If there is a difference, a warning is logged. However, the POSIX interpretation of the command is still used. The warning may be safely ignored if you are sure that the command will work as intended.

Unsupported features

The following features exist in some form either in cmd or in POSIX or both, but are not supported by Autory:

  • Command redirection and piping (e.g., >, >>, <, |)
  • Environment variable expansion (e.g., %VAR% in cmd, $VAR in POSIX)
  • Command substitution (e.g., `command` or $(command) in POSIX)
  • Conditional execution (e.g., &&, ||)
  • Wildcards and globbing (e.g., *, ?)
  • Line continuation (e.g., ^ in cmd, \ in POSIX)
  • Batch scripting features (e.g., if, for, goto in cmd)
  • Comments (e.g., REM in cmd, # in POSIX)

If you need any of these features, write a script using Python, PowerShell, or any other language that is available on your system, and call that script from Autory instead.

Technical documentation

For a deep dive into these differences, see: