Using the CLI

The oi-tools package ships a command line app for submitting and monitoring PBS jobs and viewing the package documentation while offline. The documentation for each command is given below.

Command line app for the oi-tools package.

oi docs

oi docs [OPTIONS]

Serve the oi-tools HTML documentation.

Parameters:

--build, --no-build

Rebuild the documentation before serving. [Default: False]

--serve, --no-serve

Serve the documentation on host:port. [Default: True]

--host

Hostname to serve on. [Default: 0.0.0.0]

--port

Port to serve on. [Default: 8000]

--open, --no-open

Open the documentation in the default browser. Requires serve. [Default: True]

oi sub

oi sub [OPTIONS] FILE [ARGS]

Submit a single script or module as a PBS job.

Logs are written to <log_folder>/<base_job_name>/<args>/, with one file per submission named by today’s date and an incrementing counter (e.g. logs/myscript/2001/2026-01-15-1.log).

If filetype is omitted, the filetype is inferred from the file suffix (e.g. .py → python_script, .do → stata_script). If the suffix is unrecognized, this function will falls back to "python_module".

Parameters:

FILE, --file

Path to the script or python module. [Required]

ARGS, --args, --empty-args

Command-line arguments to pass to the script or module. [Default: []]

--mem

Memory to request. Can be an integer (treated as gigabytes) or a string such as "16G". The default value is configurable via the OI_TOOLS_PBS_DEFAULT_MEM environment variable. [Default: 8G]

--cpus

Number of CPU cores to request. The default value is configurable via the OI_TOOLS_PBS_DEFAULT_CPUS environment variable. [Default: 4]

--wait, --no-wait

Whether to wait for the job to finish before returning (True) or immediately return (False). [Default: False]

--log-folder

Directory in which to create log files. Set to None to discard output. The default value is configurable via the OI_TOOLS_PBS_LOG_FOLDER environment variable. [Default: logs]

--verbose, --no-verbose

Print job details and the generated PBS script before submitting. [Default: True]

--filetype

Explicitly set the script type. [Choices: python_script, python_module, stata_script, r_script, sas_script]

--base-job-name

Base name used for the PBS job and the log subdirectory. Defaults to the script path with the suffix removed and non-alphanumeric characters replaced by hyphens (e.g. "code/myscript.py" → "code-myscript").

--python-executable

Path to the Python interpreter to use for Python jobs. Defaults to whatever version of Python is used to submit the job (sys.executable).

--cwd

Working directory for the job. Defaults to the current directory at submission time.

--env-vars

Optional dictionary of environment variables to export in the job script (e.g. {"MY_VAR": "value"}).

oi list

oi list [OPTIONS] [ARGS...]

Print PBS jobs in a formatted table.

Arguments:

USERS

Usernames indicating whose jobs to show. If omitted, shows only the current user’s jobs.

Parameters:

--all, --no-all

Show everyone’s jobs. [Default: False]

--limit

Maximum number of jobs to display. [Default: 20]

--completed, --no-completed

Include completed jobs. [Default: False]

--sort

What to sort by. [Choices: user, mem, cpus, Default: user]