NAME

xrun - Generic Docker Runner

SYNOPSIS

xrun -I IMAGE [ options ] [ command ... ]

    -h   , --help       show help
    -d   , --debug      debug mode
    -q   , --quiet      quiet mode

Docker options:
    -I # , --image      Docker image (required)
    -E # , --env        environment variable to inherit (repeatable)
    -W   , --mount-cwd  mount current working directory
    -H   , --mount-home mount home directory
    -V # , --volume     additional volume to mount (repeatable)
    -U   , --unmount    do not mount any directory
         , --mount-mode mount mode (rw or ro, default: rw)
    -R   , --mount-ro   mount read-only (shortcut for --mount-mode=ro)
    -B   , --batch      batch mode (non-interactive)
    -N # , --name       live container name
    -K   , --kill       kill and remove existing container
    -L   , --live       use live (persistent) container
    -P # , --port       port mapping (repeatable)
    -O # , --other      additional docker options (repeatable)

VERSION

Version 0.9917

DESCRIPTION

xrun is a generic Docker runner that simplifies running commands in Docker containers. It automatically configures the tedious Docker options such as volume mounts, environment variables, working directories, and interactive terminal settings, so you can focus on the command you want to run.

xrun is installed as part of App::Greple::xlate and is used by xlate for Docker operations, but it can also be used independently as a general-purpose Docker runner.

xrun uses getoptlong.sh for option parsing.

Key Features

Git Friendly: If you are working in a git environment, the git top directory is automatically mounted. Otherwise the current directory is mounted.
Live Container: Use -L to create or attach to a persistent container that survives between invocations. Container names are automatically generated from the image name and mount directory.
Environment Inheritance: Common environment variables are automatically inherited: LANG, TZ, proxy settings, terminal settings, and API keys for AI/LLM services (DeepL, OpenAI, Anthropic, Perplexity).
Flexible Mounting: Various mount options: current directory (-W), home directory (-H), additional volumes (-V), read-only mode (-R), or no mount (-U).
X11 Support: When DISPLAY is set, the host IP is automatically detected and passed to the container, enabling GUI applications.
Configuration File: Use .xrunrc to set default options. Searched in current directory, git top directory, and home directory.
Standalone Operation: xrun can operate independently of xlate. If the App::Greple::xlate module is installed, xrun uses getoptlong.sh bundled with the module. Otherwise, it searches for getoptlong.sh in the standard PATH. This allows xrun to be used as a general-purpose Docker runner even without the xlate module.

OPTIONS

-h, --help: Show help message.
-d, --debug: Enable debug mode.
-q, --quiet: Quiet mode.
-I image, --image=image: Specify Docker image. Required, but you can put it in .xrunrc so you don't have to type it every time.
-E name[=value], --env=name[=value]: Specify environment variable to inherit. Repeatable.
-W, --mount-cwd: Mount current working directory.
-H, --mount-home: Mount home directory.
-V from:to, --volume=from:to: Specify additional directory to mount. Repeatable.
-U, --unmount: Do not mount any directory.
--mount-mode=mode: Set mount mode. mode is either rw (read-write, default) or ro (read-only).
-R, --mount-ro: Mount directory as read-only. Shortcut for --mount-mode=ro.
-B, --batch: Run in batch mode (non-interactive).
-N name, --name=name: Specify container name explicitly.
-K, --kill: Kill and remove existing container.
-L, --live: Use live (persistent) container.
-P port, --port=port: Specify port mapping (e.g., 8080:80). Repeatable.
-O option, --other=option: Specify additional docker options. Repeatable.

LIVE CONTAINER

The -L option enables live (persistent) container mode. Unlike normal mode where containers are removed after execution (--rm), live containers persist between invocations, allowing you to maintain state and reduce startup overhead.

Container Lifecycle

When -L is specified, xrun behaves as follows:

1. Container exists and is running: If a command is given, execute it using docker exec. Otherwise, attach to the container using docker attach.
2. Container exists but is exited: Start the container with docker start, then proceed as above.
3. Container exists but is paused: Unpause the container with docker unpause, then proceed as above.
4. Container does not exist: Create a new persistent container (without --rm flag).

Container Naming

Container names are automatically generated in the format:

<image_name>.<mount_directory>

For example, if you run:

xrun -I tecolicom/xlate -L

from /home/user/project, the container name would be xlate.project.

You can override the auto-generated name using the -N option:

xrun -I tecolicom/xlate -L -N mycontainer

Managing Live Containers

Attach to existing container

xrun -I myimage -L

If no command is given, attaches to the container's main process.

Execute command in existing container

xrun -I myimage -L ls -la

Runs the command in the existing container using docker exec.

Kill and recreate container

xrun -I myimage -KL

The -K option removes the existing container before -L creates a new one. Useful when you need a fresh container state.

Kill container only

xrun -I myimage -K

Without -L, the container is removed and the command exits.

Interactive Mode

In live container mode, interactive mode (-i and -t flags for Docker) is automatically enabled when:

Standard input is a terminal (TTY)
The -B (batch) option is not specified

This allows seamless interactive use when attaching to containers or running interactive commands.

CONFIGURATION FILE

.xrunrc is searched in the following order:

1. Current directory
2. Git top directory (if different)
3. Home directory

All matching files are read and their options are prepended to the command line arguments. This means you can use any command line option in the configuration file:

# Example .xrunrc
-I tecolicom/xlate:latest
-L
-E CUSTOM_VAR=value
-V /data:/data

Lines starting with # are treated as comments.

Option Priority

Options are processed in this order (later values override earlier):

1. Home directory .xrunrc
2. Git top directory .xrunrc
3. Current directory .xrunrc
4. Command line arguments

ENVIRONMENT

Inherited Variables

The following environment variables are inherited by default:

LANG TZ
HTTP_PROXY HTTPS_PROXY http_proxy https_proxy
TERM_PROGRAM TERM_BGCOLOR COLORTERM
DEEPL_AUTH_KEY OPENAI_API_KEY ANTHROPIC_API_KEY LLM_PERPLEXITY_KEY

Container Variables

The following environment variables are set inside the container:

XRUN_RUNNING_ON_DOCKER=1: Indicates the command is running inside a container started by xrun.
XLATE_RUNNING_ON_DOCKER=1: For compatibility with xlate. Used to prevent recursive Docker invocation when xlate is run inside the container.

EXAMPLES

# Run a command in container
xrun -I ubuntu:latest echo hello

# Attach to live container
xrun -I myimage:v1 -L

# Run bash with specific image
xrun -I myimage:v1 bash

# Kill and restart live container
xrun -I myimage:v1 -KL

AUTHOR

Kazumasa Utashiro

LICENSE

This software is released under the MIT License. https://opensource.org/licenses/MIT

To install App::Greple::xlate, copy and paste the appropriate command in to your terminal.

cpanm

cpanm App::Greple::xlate

CPAN shell

perl -MCPAN -e shell
install App::Greple::xlate

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)