Configuration
Overview¶
Posting can be configured using a configuration file, environment variables, and/or .env
files.
Configuration values are loaded in the following order of precedence (highest to lowest):
- Configuration file
- Environment variables
.env
files
Configuration file¶
You can write configuration for Posting using YAML.
The location of the config file can be checked using the command posting locate config
.
Here's an example configuration file:
theme: galaxy
layout: horizontal
response:
prettify_json: false
heading:
visible: true
show_host: false
Environment variables¶
All configuration values can also be set as environment variables.
Simply prefix the name of the config with POSTING_
and set it as an environment variable.
For nested configuration values, use __
as the delimiter. So to set heading.visible
to false
, you can set the environment variable POSTING_HEADING__VISIBLE=false
.
For example, to set the theme to galaxy
, you can set the environment variable POSTING_THEME=galaxy
.
dotenv (.env
) files¶
Posting also supports .env
(dotenv) files, which are useful if you want to swap out environment variable values depending on the environment you're working in (for example, "dev" vs "prod").
You can tell Posting to use a .env
file using the --env
option.
This option can be supplied multiple times to load multiple .env
files.
Here's an example .env
file:
POSTING_THEME="cobalt"
POSTING_LAYOUT="vertical"
POSTING_HEADING__VISIBLE="false"
Dotenv files are separate from collections, although you may wish to include them inside a collection to make it easy to version and share with others.
Configuring SSL¶
Posting verifies SSL certificates by default using the CA bundle provided by the certifi
package.
SSL certificate configuration¶
Posting can load custom CA bundles from a .pem
file.
The easiest way to do this is in your config.yaml
file:
ssl:
ca_bundle: 'absolute/path/to/certificate.pem'
Environment-specific certificates¶
If the required CA bundle differs per environment, you can again use the principle that all configuration can be set as environment variables which can optionally be set and loaded using --env
and .env
files:
# dev.env
POSTING_SSL__CA_BUNDLE='/path/to/certificate.pem'
Now load the dev.env
file when working in the dev
environment to ensure the dev environment CA bundle is used:
posting --env dev.env
Disabling SSL verification¶
SSL verification can be disabled on a per-request basis in the "Options" tab.
Client-side certificates¶
You can specify local certificates to use as a client-side certificate:
ssl:
certificate_path: /path/to/certificate.pem
key_file: /path/to/key.key # optional
password: '***********' # optional password for key_file
Full configuration reference¶
The table below lists all available configuration options and their environment variable equivalents, their default values, and descriptions.
Config Key (Env Var) | Values (Default) | Description |
---|---|---|
theme (POSTING_THEME ) |
"posting" , "galaxy" , "monokai" , "solarized-light" , "nautilus" , "nebula" , "alpine" , "cobalt" , "twilight" , "hacker" (Default: "posting" ) |
Sets the theme of the application. |
load_user_themes (POSTING_LOAD_USER_THEMES ) |
true , false (Default: true ) |
If enabled, load user themes from the theme directory, allowing them to be specified in config and selected via the command palette. |
load_builtin_themes (POSTING_LOAD_BUILTIN_THEMES ) |
true , false (Default: true ) |
If enabled, load builtin themes, allowing them to be specified in config and selected via the command palette. |
theme_directory (POSTING_THEME_DIRECTORY ) |
(Default: ${XDG_DATA_HOME}/posting/themes ) |
The directory containing user themes. |
layout (POSTING_LAYOUT ) |
"vertical" , "horizontal" (Default: "horizontal" ) |
Sets the layout of the application. |
use_host_environment (POSTING_USE_HOST_ENVIRONMENT ) |
true , false (Default: false ) |
Allow/deny using environment variables from the host machine in requests via $env: syntax. When disabled, only variables defined explicitly in .env files will be available for use. |
watch_env_files (POSTING_WATCH_ENV_FILES ) |
true , false (Default: true ) |
If enabled, automatically reload environment files when they change. |
animation (POSTING_ANIMATION ) |
"none" , "basic" , "full" (Default: "none" ) |
Controls the animation level. |
response.prettify_json (POSTING_RESPONSE__PRETTIFY_JSON ) |
true , false (Default: true ) |
If enabled, JSON responses will be pretty-formatted. |
response.show_size_and_time (POSTING_RESPONSE__SHOW_SIZE_AND_TIME ) |
true , false (Default: true ) |
If enabled, the size and time taken for the response will be displayed in the response area border subtitle. |
heading.visible (POSTING_HEADING__VISIBLE ) |
true , false (Default: true ) |
Show/hide the app header. |
heading.show_host (POSTING_HEADING__SHOW_HOST ) |
true , false (Default: true ) |
Show/hide the hostname in the app header. |
heading.show_version (POSTING_HEADING__SHOW_VERSION ) |
true , false (Default: true ) |
Show/hide the version in the app header. |
heading.hostname (POSTING_HEADING__HOSTNAME ) |
(Default: unset ) |
The hostname to display in the app header. You may use Rich markup here. If unset, the hostname provided via socket.gethostname() will be used. |
url_bar.show_value_preview (POSTING_URL_BAR__SHOW_VALUE_PREVIEW ) |
true , false (Default: true ) |
Show/hide the variable value preview below the URL bar. |
collection_browser.position (POSTING_COLLECTION_BROWSER__POSITION ) |
"left" , "right" (Default: "left" ) |
The position of the collection browser on screen. |
collection_browser.show_on_startup (POSTING_COLLECTION_BROWSER__SHOW_ON_STARTUP ) |
true , false (Default: true ) |
Show/hide the collection browser on startup. Can always be toggled using the command palette. |
pager (POSTING_PAGER ) |
(Default: $PAGER ) |
Command to use for paging text. |
pager_json (POSTING_PAGER_JSON ) |
(Default: $PAGER ) |
Command to use for paging JSON. |
editor (POSTING_EDITOR ) |
(Default: $EDITOR ) |
Command to use for opening files in an external editor. |
ssl.ca_bundle (POSTING_SSL__CA_BUNDLE ) |
Absolute path (Default: unset ) |
Absolute path to a CA bundle file/dir. If not set, the Certifi CA bundle will be used. |
ssl.certificate_path (POSTING_SSL__CERTIFICATE_PATH ) |
Absolute path (Default: unset ) |
Absolute path to a client SSL certificate file or directory. |
ssl.key_file (POSTING_SSL__KEY_FILE ) |
Absolute path (Default: unset ) |
Absolute path to a client SSL key file. |
ssl.password (POSTING_SSL__PASSWORD ) |
Password for the key file. (Default: unset ) |
Password to decrypt the key file if it's encrypted. |
focus.on_startup (POSTING_FOCUS__ON_STARTUP ) |
"url" , "method", "collection" (Default: "url" ) |
Automatically focus the URL bar, method, or collection browser when the app starts. |
focus.on_response (POSTING_FOCUS__ON_RESPONSE ) |
"body" , "tabs" (Default: unset ) |
Automatically focus the response tabs or response body text area when a response is received. |
focus.on_request_open (POSTING_FOCUS__ON_REQUEST_OPEN ) |
"headers" , "body" , "query" , "info" , "url" , "method" (Default: unset ) |
Automatically focus the specified target when a request is opened from the collection browser. |
text_input.blinking_cursor (POSTING_TEXT_INPUT__BLINKING_CURSOR ) |
true , false (Default: true ) |
If enabled, the cursor will blink in input widgets and text area widgets. |
command_palette.theme_preview (POSTING_COMMAND_PALETTE__THEME_PREVIEW ) |
true , false (Default: false ) |
If enabled, the command palette will display a preview of the selected theme when the cursor is over it. This will slow down cursor movement and so is disabled by default. |
use_xresources (POSTING_USE_XRESOURCES ) |
true , false (Default: false ) |
Try to create themes called xresources-dark and xresources-light (see the section below) |