Configuration - Nukesor/pueue GitHub Wiki

The default configuration file of Pueue is located in one of these directories respectively:

  • Linux: $XDG_CONFIG_HOME/pueue/pueue.yml or ~/.config/pueue/pueue.yml.
  • macOS: ~/Library/Application Support/pueue/pueue.yml
  • Windows: %APPDATA%\pueue\pueue.yml

A default configuration file will be generated when starting pueued for the first time. You can also force pueue to use a specific configuration file with the -c flag for both the daemon and the client. Alternatively, you can set the PUEUE_CONFIG_PATH environment variable. Please note that using the command line option will overwrite the environment variable.

Most config values can just be omitted and Pueue will pick the default value.

---
shared:
  pueue_directory: ~/.local/share/pueue
  use_unix_socket: true
  runtime_directory: null
  unix_socket_path: ~/.local/share/pueue/pueue_your_user.socket
  host: "localhost"
  port: "6924"
  daemon_cert: ~/.local/share/pueue/certs/daemon.cert
  daemon_key: ~/.local/share/pueue/certs/daemon.key
  shared_secret_path: ~/.local/share/pueue/shared_secret

client:
  restart_in_place: false
  read_local_logs: true
  show_confirmation_questions: false
  show_expanded_aliases: false
  dark_mode: false
  max_status_height: null
  status_time_format: "%H:%M:%S"
  status_datetime_format: "%Y-%m-%d\n%H:%M:%S"

daemon:
  pause_group_on_failure: false
  pause_all_on_failure: false
  callback: "\"Task {{ id }}\nCommand: {{ command }}\nPath: {{ path }}\nFinished with status '{{ result }}'\""
  callback_log_lines: 10
  shell_command: ["zsh", "-c", "{{ pueue_command_string }}"]
  env_vars:
    BASH_ENV: "$HOME/.config/shell_aliases"

Shared

  • pueue_directory The location Pueue uses for its intermediate files and logs, uses $XDG_DATA_HOME/pueue if not specified.
  • runtime_directory The location for runtime variables. Defaults to pueue_directory or $XDG_RUNTIME_DIR.
  • use_unix_socket (Unix only) Whether the daemon should listen on a Unix- or a TCP-socket.
  • unix_socket_path (Unix only) The path the unix socket is located at. Defaults to runtime_directory/pueue_$USER.socket.
  • host The host the daemon listens on and the client connects to. Only used when in TCP mode.
  • port The port the daemon listens on and the client connects to. Only used when in TCP mode.
  • daemon_cert The TLS certificate used for encrypting any TCP traffic.
  • daemon_key The TLS private key used for encrypting any TCP traffic.
  • shared_secret_path The path to the file, which contains the secret used for authentication with the daemon.

Client

  • restart_in_place If this is set to true, tasks will always be restarted in place instead of creating a new identical task. Beware: Restarting in place overwrites logs from the previous run.
  • read_local_logs If the client runs on the same machine as the daemon, logs don't have to be sent via the socket. Instead they can be read directly from the disk.
  • show_confirmation_questions The client will print warnings that require confirmation for different critical commands.
  • show_expanded_aliases Determines, whether the original command or the command after expanding any aliases in the pueue_aliases file will be shown when calling pueue status.
  • dark_mode Switch to dark colors instead of standard colors in the command output. This option can be helpful in non-standard terminal themes.
  • max_status_height [int|null] If a number X is given, all table rows in the status subcommand, which have more than X lines will be truncated.
  • status_time_format The time format string that should be used in pueue status. Check this page for formatting syntax
  • status_datetime_format The datetime format string that will be used in pueue status.

Daemon

  • pause_group_on_failure If set to true, on task failure, the daemon pauses queued tasks in the same group as the failed task. Already running tasks will continue.
  • pause_all_on_failure If set to true, on task failure, the daemon pauses all queued tasks in all groups. Already running tasks will continue.
  • callback The command that will be called after a task finishes. Can be parameterized
  • callback_log_lines The amount of stdout/stderr lines that are available in the callback.
  • shell_command: This can be used to run commands in a custom shell. Any occurence of {{ pueue_command_string }} in one of the parameters will be expanded to the task's. This feature can lead to unexpected behavior as other shells might behave differently. Use at your own risk.
  • env-vars (Dictionary): These variables will be injected into all tasks.

Profiles

It's possible to have multiple configuration profiles in the same configuration file.

The profile is then selected via the commandline: pueue --profile remote status

An example for such a config might look like this:

---
shared:
  use_unix_socket: true
  host: 127.0.0.1
  port: "6924"
client:
  restart_in_place: true
  read_local_logs: true
  max_status_lines: 10
daemon:
  pause_group_on_failure: false
  pause_all_on_failure: false
profiles:
profiles:
  remote:
    shared:
      use_unix_socket: false
      host: some.remote_host.com
      port: "6924"
      daemon_cert: ~/.local/share/pueue/certs/remote_daemon.cert
      shared_secret_path: ~/.local/share/pueue/remote_shared_secret