Skip to content

Command setup

Setting extra environment vars

In some cases you may want to set environment variables for a single command only. In this case, you can use the extra_env config option, which adds YAML key:value pairs to the environment for just that command (and the before / after commands, see below).

I use this method to set the terminal width for the rich-codex screenshots in this documentation:

<!-- RICH-CODEX
terminal_width: 120
notrim: true
extra_env:
  TERMINAL_WIDTH: 120
-->
![`rich-codex --help`](../img/rich-codex-cli-envs.svg)

Tip

It's probably easier to set these at run-level if that's an option, these are really only if you want to customise for a single output.

To set environment variables for every command instead, use the top level of a config file:

extra_env:
  MY_TOOL_NO_COLOR: "1"

..or --extra-env / $EXTRA_ENV / extra_env (command line / environment variable / GitHub action key), with one KEY=value pair per line:

rich-codex --extra-env "MY_TOOL_NO_COLOR=1"

Both are merged with any per-image extra_env, which takes precedence for keys set in both places.

Repeated commands

If the same command is found more than once in a file, rich-codex runs it once and saves the result to every filename that asked for it. This keeps runs fast and the images consistent, which is usually what you want when an example is shown in more than one place. Commands found in different files always run separately.

Sometimes it isn't: if you're documenting a sequence of steps, the same command can legitimately give different output each time it runs. Use --no-dedupe / $NO_DEDUPE / no_dedupe (command line / environment variable / GitHub action key) to run every command where it's found, so that each screenshot captures its own run.

Note

Identical requests - same command, same config, same filenames - are still collapsed into one, as running them separately would only overwrite the same file twice.

Faking simple commands

Sometimes you may need to have long complicated commands to get the screenshot you need, when the typical command for an end user would be much simpler.

In this case, you can fake the command shown in the terminal prompt using --fake-command / $FAKE_COMMAND / fake_command.

For example:

<!-- RICH-CODEX fake_command: "my_tool --is-simple" -->
![`echo "I won't tell if you don't 🤫" > temp_file.txt && echo "" && cat temp_file.txt && rm temp_file.txt`](../img/fake_command.svg)

Running commands before and after

Chaining complex commands may not always work if the setup / cleanup commands generate output that you don't want to show in the screenshot.

In these more complex scenarios, you can run additional commands before and after the one used for the screenshot. This is done with the following options:

  • --before-command / $BEFORE_COMMAND / before_command
  • --after-command / $AFTER_COMMAND / after_command.

These run separate subprocess calls with the specified commands before and after the target command. This can be useful for initialising an environment and then cleaning up afterwards.

For example:

<!-- RICH-CODEX
before_command: >
  echo "This is a very simple example" > before_after_command_example.txt
after_command: rm before_after_command_example.txt
-->
![`cat before_after_command_example.txt`](../img/before_after_command.svg)

!!! note: Commands should be a single string, so remember to chain using && and ideally use YAML multi-line strings that collapse newlines using >.