Command line¶

When Sympathy is installed in your python environment you can run python -m sympathy to access the command line interface.

For a comprehensive list of commands and options, see All command line options.

Top-level commands¶

Running python -m sympathy --help will print the top level commands available.

gui: run Sympathy in GUI mode
cli: run Sympathy in CLI mode
viewer: run the viewer for sydata files
doc: generate documentation files
install: install Sympathy (start menu, file associations)
uninstall: uninstall Sympathy (start menu, file associations)
clear: cleanup temporary files

Command options¶

As mentioned there are several top level commands. Most of which have their own options.

In order to list the options available for a command, run sympathy adding the desired command and --help to the command line. For example, python -m sympathy gui --help shows the available options for running Sympathy in GUI mode.

Noteable examples¶

Here are a few examples that might be useful, for the full list please use the --help flag.

Run Sympathy for Data GUI:

python -m sympathy gui

Run Sympathy for Data CLI, executing a specified syx-workflow-file:

python -m sympathy cli filename

Build documentation for Sympathy for the platform and standard library.

python -m sympathy doc -v --library-dir <LIBRARY-DIR>

Shortcuts¶

Depending on how Sympathy was installed, you might also have shortcuts available to some commands.

Wheel installer:

sympathy (python -m sympathy)
sympathy cli (python -m sympathy cli)
sympathy gui (python -m sympathy gui)

Windows installer:

RunSympathyCLI.exe (python -m sympathy cli)
RunSympathyGUI.exe (python -m sympathy gui)

Using environment variables¶

Environment variable expansion is useful in node configurations where the node should behave differently depending on the environment where it is executed. A simple example would be a workflow that always loads a certain file from the current user’s home directory. To achieve that you can simply configure a Datasource node to point to $(HOME)/somefile.txt and it will point to the file somefile.txt in the user’s home directory.

Apart from using already existing OS environment variables you can also add your own environment variables at three different levels: OS/shell, workflow, and global. Workflow level variables are generally preferred as they do not risk affecting workflows that they should not affect.

Default workflow environment variables¶

A few variables are always defined in every workflow. $(SY_FLOW_FILEPATH) holds the full path to the workflow file, and $(SY_FLOW_DIR) contains the directory of the workflow file. These variables behave just like normal workflow variables, but they are not stored in a syx-file. Instead they are computed on the fly when they are used. Check properties for a flow to see what values these variables have for that flow.

Adding OS/shell environment variables¶

Setting environment variables or shell variables is done differently depending on operating system, version, shell, and so on. As an example let us set the shell variable GREETING and start Sympathy in a command prompt in Windows:

> set GREETING=Hi!
> RunSympathyGUI.exe

Add a Hello world example node and configure it to display $(GREETING). Run the node. The output should be Hi!.

Adding workflow environment variables¶

Workflow level environment variables can be added and removed via the preferences GUI. Right click in your flow and click Properties and go to the tab Environment variables, where you can add, change, and remove workflow variables. These variables are stored in the workflow file, and will only affect that workflow, and its subflows. A subflow can always override a variable set by one of its parent flows.

Adding environment variables to the global file¶

Just as workflow level variables, global variables can be added and edited in Environment Preferences but they are stored in the global config file for Sympathy so they affect all workflows.

Priority¶

In case of name conflicts, environment variables are looked up in the following order:

OS/shell
Workflow (defined in current subflow)
Workflow (defined in a parent workflow)
Global settings

Special variables¶

SY_OVERRIDE_TEMP_PATH: Used to override the folder where session data (temporary files) are stored. The temporary path may in turn contain environment variables.

Passing credentials via environment variables¶

Credentials can be passed to gui and cli via environment variables. To so, use –environment-credentials PREFIX. They need to follow a specific data format to be used.

The variable name must start with PREFIX. After matching, the prefix is not considered to be part of the name, the remaining part of the name should be a parse-able to a list of strings using json. There must be a credential type that can be constructed from the strings.
The variable value should be parse-able to a dictionary in the same format as is returned by BasicNode.require_credentials.

Here are 3 examples for the different credential types.

Secret credential

Name:: SFD[“secret”,”<secret-name>”]
Value:: {“secret”:”<secret-value>”}

Login credential

Name:: SFD[“login”,”<login-name>”]
Value:: {“username”:”<username>”,”password”:”<password>”}

Azure credential

Name:: SFD[“azure”,”<client-name>”,”<login-name>”]
Value:: {“token”:”<azure-token>”,”expires_on”:<timestamp>}

Note that expires_on is an integer.

While it can be tricky to enter such variables from the shell, it should be possible to do for the intended usescase which is to supply the application with sensitive information when running in a headless environment.