# Command Line Interface

Ren'Py includes a command line interface (CLI) that can be used to automate some development tasks, allowing for continuous integration and for scripting releases. For most purposes, this isn't necessary - all these tasks can be done through the Ren'Py launcher.

The examples on this page assume you're running the CLI from the Ren'Py SDK directory (the directory that contains renpy.py, renpy.sh, and renpy.exe). Examples are provided for Linux/macOS, and Windows.

The CLI isn't a stable interface - it may change between Ren'Py releases, as required. This page is current as of Ren'Py 8.5.3.

## Quick Tasks

Use these quick workflows as copy-paste starting points. Replace paths/language codes as needed.

### Run project

    cd /path/to/renpy
    ./renpy.sh /path/to/project run

    cd C:\path\to\renpy
    .\lib\py3-windows-x86_64\python.exe renpy.py C:\path\to\project run

### Build distributions

Build desktop distributions (Windows/macOS/Linux) from the launcher tool.

    cd /path/to/renpy
    ./renpy.sh launcher distribute /path/to/project --destination /path/to/output

    cd C:\path\to\renpy
    .\lib\py3-windows-x86_64\python.exe renpy.py launcher distribute C:\path\to\project --destination C:\path\to\output

### Generate/update translations

Generate or update translation files, then export dialogue/strings for translators.

    cd /path/to/renpy
    ./renpy.sh /path/to/project translate french
    ./renpy.sh /path/to/project dialogue french --strings

    cd C:\path\to\renpy
    .\lib\py3-windows-x86_64\python.exe renpy.py C:\path\to\project translate french
    .\lib\py3-windows-x86_64\python.exe renpy.py C:\path\to\project dialogue french --strings

## Syntax

Note

Notation used on this page:

- `<name>` is a value you replace, such as a project path or language code.

- `[item]` is optional and does not need to be included.

    ./renpy.sh [global options...] [<basedir>] [<command>] [command options...]

    .\lib\py3-windows-x86_64\python.exe renpy.py [global options...] [<basedir>] [command] [command options...]

<basedir>
  Default:

    The directory containing the Ren'Py executable (the launcher)

  In the description of the commands below, <basedir> is the path to the base directory of the project.

<command>
  Default:

    `run`

  Specifies the command to execute.

### Global options

The following flags may be used with any command:

--savedir <directory>

  Specifies the directory where saves and persistent data are placed.

--trace <level>

  Specifies the level of trace Ren'Py will log to trace.txt. (1=per-call, 2=per-line)

--version

  Displays the version of Ren'Py in use.

--compile

  Forces all .rpy scripts to be recompiled before proceeding.

--compile-python

  Forces all Python files to be recompiled, rather than read from `game/cache/bytecode-*.rpyb`.

--keep-orphan-rpyc

  If compiling, prevents Ren'Py from deleting `.rpyc` files that are not associated with a `.rpy` or `_ren.py` file of the same name.

--errors-in-editor

  Causes errors to open in a text editor.

--safe-mode

  Forces Ren'Py to start in safe mode, allowing the player to configure graphics.

--help, -h

  Displays a help message showing commands and syntax, then exits. This returns the most up-to-date command information.

Ren'Py can dump information about the game to a JSON file. These options let you select the file, and choose what is dumped.

--json-dump <file>

  Specifies the name of the JSON file.

--json-dump-private

  Includes private names in the dump. (Names beginning with an underscore _)

--json-dump-common

  Includes names defined in the common directory in the dump.

Note

The CLI may change between different releases. To see the latest commands and flags, run:

    ./renpy.sh --help

    .\lib\py3-windows-x86_64\python.exe renpy.py --help

To see the latest options for a particular command, run:

    ./renpy.sh <basedir> <command> --help

    .\lib\py3-windows-x86_64\python.exe renpy.py <basedir> <command> --help

## Core Workflow Commands

### Run Project

Runs the current project normally. This is the default command that is run if no command is given.

    ./renpy.sh <basedir> run [options...]

    .\lib\py3-windows-x86_64\python.exe renpy.py <basedir> run [options...]

--profile-display

  Reports the amount of time it takes to draw the screen.

  Equivalent to setting `config.profile` to True.

--debug-image-cache

  Writes information about the image cache to image_cache.txt.

  Equivalent to setting `config.debug_image_cache` to True.

--warp <filename:linenumber>

  Tries to warp to just before the specified line. This takes as an argument a `filename:linenumber` pair.

  The warp feature requires `config.developer` to be True to operate.

### Quit

Quits the game immediately.

    ./renpy.sh <basedir> quit

    .\lib\py3-windows-x86_64\python.exe renpy.py <basedir> quit

### Compile

Compiles the game, creating .rpyc files from .rpy files. The equivalent of the "Force Recompile" button in the Ren'Py launcher.

    ./renpy.sh <basedir> compile [--keep-orphan-rpyc]

    .\lib\py3-windows-x86_64\python.exe renpy.py <basedir> compile [--keep-orphan-rpyc]

--keep-orphan-rpyc

  Prevents Ren'Py from deleting `.rpyc` files that are not associated with a `.rpy` or `_ren.py` file of the same name.

### Interactive Director

Starts the Interactive Director and runs the game afterwards.

    ./renpy.sh <basedir> director

    .\lib\py3-windows-x86_64\python.exe renpy.py <basedir> director

### Remove Persistent Data

Deletes Persistent Data data. This can be handy since persistent data is found in multiple locations:

- the game save folder

- the location specified by `config.save_directory`

    ./renpy.sh <basedir> rmpersistent

    .\lib\py3-windows-x86_64\python.exe renpy.py <basedir> rmpersistent

Warning

This will reset all game progress, including unlocks, read messages, and preferences.

### Update Project

Download and install updates to a Ren'Py game from a web host. For more information, see HTTPS/HTTP Updater.

The parameters are identical to those used in `updater.update()`.

    ./renpy.sh <basedir> update <url> [options...]

    .\lib\py3-windows-x86_64\python.exe renpy.py <basedir> update <url> [options...]

<url>

  Specifies the URL to the updates.json file.

--base <directory>

  Specifies the base directory of the game to update. Defaults to the current game.

--force

  Forces the update to run even if the version numbers are the same.

--key <key>

  A file giving the public key to use of the update.

--simulate <option>

  A simulation mode to test update GUIs without actually performing an update. One of `available`, `not_available`, or `error`.

Warning

This will modify your game's files. Use with caution.

## Validation and Testing

### Check Script (Lint)

This runs a Lint report on the game. This checks the script for errors and prints script statistics. It's equivalent to the "Check Script (Lint)" button in the launcher.

    ./renpy.sh <basedir> lint [<filename>] [options...]

    .\lib\py3-windows-x86_64\python.exe renpy.py <basedir> lint [<filename>] [options...]

<filename>

  If given, the lint report will be written to this file rather than printed to standard output.

--error-code

  Exits with an error code of 1 if there was a lint error. This is useful for CI systems to detect when lint fails.

--no-orphan-tl

  Does not report orphan translations. Orphaned translations are Translation Statements that do not reference a string in the primary language.

--reserved-parameters

  Reports Ren'Py or python reserved names in renpy statement parameters.

  In particular it looks for label, screen, and ATL statements.

--by-character

  Reports the count of blocks, words, and characters for each character.

--check-unclosed-tags

  Reports unclosed text tags.

--all-problems

  Reports all problems of a kind, not just the first ten issues.

### Run Testcases

This runs automated tests on the game.

    ./renpy.sh <basedir> test [<filters>] [options...]

    .\lib\py3-windows-x86_64\python.exe renpy.py <basedir> test [<filters>] [options...]

See Automated Testing for more information.

## Build and Distribution

Note

As part of the build process, Ren'Py will create .rpyc files that contain information that load the game. A continuous integration system should preserve these .rpyc files after a build, and supply them to the next build, either directly or in the old-game directory. Failure to do so may result in a game that can't load saves.

### Add From To Calls

Adds a `from` clause to each call statement that does not have one. Generally, this should be done before a release, to help Ren'Py locate the return point of calls in a modified game.

Implies `--compile`.

    ./renpy.sh <basedir> add_from

    .\lib\py3-windows-x86_64\python.exe renpy.py <basedir> add_from

Warning

This will modify your game's script files.

### Distribute

Builds distributions of the game for Windows, macOS, and Linux.

    ./renpy.sh launcher distribute <basedir> [options...]

    .\lib\py3-windows-x86_64\python.exe renpy.py launcher distribute <basedir> [options...]

--destination <directory>

  Specifies the directory to place the distributions in. The default is a directory named "name-version-dists" in the current directory, taking information from `build.name` and `build.version`.

--format <format>

  Forces the format of the distribution to be this.

--macapp <app>

  Specifies the path to a macapp that's used to sign mac packages instead of the macapp that's included with Ren'Py.

--no-archive

  Does not add files to Archives.

--no-update

  Does not build update files which allow the HTTPS/HTTP Updater to work.

--package <package>

  Specifies the name of the package to build, where package is a package name like "pc", "mac", or "markets". This option can be given multiple times to build multiple packages. The default is to build all packages.

--packagedest <package>

  Specify the output name for a package (without any extensions). Requires that exactly one `--package` is specified.

### Android Build

This builds a release of the game for Android. It's assumed that the launcher has been used to install the Android SDK, generate keys, and configure the project.

    ./renpy.sh launcher android_build <basedir> [options...]

    .\lib\py3-windows-x86_64\python.exe renpy.py launcher android_build <basedir> [options...]

--destination <directory>

  Specifies the directory to place the output in. The default is a directory named "name-version-dists" in the current directory, taking information from `build.name` and `build.version`.

--bundle

  Produces a `.aab` bundle if given. If not given, Ren'Py will produce a `.apk` file.

--install

  Installs the `.apk` or `.aab` file to a connected device.

--launch

  Launches the game on a connected device. This implies `--install`.

--package <package>

  Specifies the package to build. Defaults to building the 'android' package.

### iOS Create

Creates an Xcode project that can be used to build an iOS version of the game. It's assumed that the launcher has been used to install iOS support once.

    ./renpy.sh launcher ios_create <basedir> <destination>

    .\lib\py3-windows-x86_64\python.exe renpy.py launcher ios_create <basedir> <destination>

<basedir>

  Specifies the path to the Ren'Py project.

<destination>

  Specifies the path to the iOS project that will be created.

### iOS Populate

Copies the game into an Xcode project created by ios_create. This is used to update a project created with the same version of Ren'Py.

    ./renpy.sh launcher ios_populate <basedir> <destination>

    .\lib\py3-windows-x86_64\python.exe renpy.py launcher ios_populate <basedir> <destination>

<basedir>

  Specifies the path to the Ren'Py project.

<destination>

  Specifies the path to the iOS project that will be updated.

### Web Build

Builds a release of the game for web. It's assumed that the launcher has been used to install web support and that any configuration files (such as `progressive_download.txt`) are in place.

    ./renpy.sh launcher web_build <basedir> [options...]

    .\lib\py3-windows-x86_64\python.exe renpy.py launcher web_build <basedir> [options...]

--destination <directory>

  Specifies the directory where the packaged files should be placed.

--launch

  Starts a webserver and launches the game after build.

## Translation and Localization

See also

- Translation

### Translate

Creates or updates translation files in `tl/<language>` for the project. It writes missing dialogue and string entries while leaving existing translated entries unchanged. Use `--count` to report missing translations without writing files.

    ./renpy.sh <basedir> translate <language> [options...]

    .\lib\py3-windows-x86_64\python.exe renpy.py <basedir> translate <language> [options...]

<language>

  Specifies the language to generate translations for.

--count

  Prints a count of missing translations without generating files.

--rot13

  Applies rot13 while generating translations.

--piglatin

  Applies pig latin while generating translations. Overridden by `--rot13`.

--empty

  Produces empty strings while generating translations. Overridden by `--rot13` and `--piglatin`.

--min-priority <int>

  Translates strings with priority greater than this value.

--max-priority <int>
  Default:

    499 if `config.translate_launcher` is True, otherwise 299.

  Translates strings with less than this priority.

--strings-only

  Only translates strings (not dialogue).

--common-only

  Only translates strings from common code.

--no-todo

  Does not include the TODO flag at the top of generated translation files.

--string <string>

  Translates a specific string. This option can be given multiple times to translate multiple strings.

### Dialogue

Exports dialogue (and optionally translatable strings) to `dialogue.tab` by default, or `dialogue.txt` when `--text` is used.

If a language is provided, it outputs translated text when available. Otherwise, it outputs source text.

    ./renpy.sh <basedir> dialogue <language> [options...]

    .\lib\py3-windows-x86_64\python.exe renpy.py <basedir> dialogue <language> [options...]

Note

This is an export/reporting command. It does not create `tl/<language>` translation script files.

<language>

  Specifies the language to extract dialogue for.

--text

  Outputs the dialogue as plain text. If not given, outputs a tab-delimited file.

--strings

  Outputs all translatable strings, not just dialogue.

  Most of these are defined with the `_()` and `__()` functions, as well as menu choices.

--notags

  Strips text tags from the dialogue.

--escape

  Escapes quotes and other special characters.

### Extract Strings

Exports existing translations from the game to a JSON file.

    ./renpy.sh <basedir> extract_strings <language> <destination> [options...]

    .\lib\py3-windows-x86_64\python.exe renpy.py <basedir> extract_strings <language> <destination> [options...]

<language>

  Specifies the language to extract translated strings from.

<destination>

  Specifies the json file to store the translated strings into.

--merge

  Merges the current contents of the file with new contents, preserving existing translations.

--force

  Does not throw exceptions if the language does not exist.

### Merge Strings

Imports translations from JSON file back into the game.

Implies `--compile`.

    ./renpy.sh <basedir> merge_strings <language> <source> [options...]

    .\lib\py3-windows-x86_64\python.exe renpy.py <basedir> merge_strings <language> <source> [options...]

<language>

  Specifies the language to merge translated strings to.

<source>

  Specifies the json file to take translated strings from.

--reverse

  Reverses the languages in the json file.

--replace

  Replaces non-trivial translations. A trivial translation is one that does not exist or if the translation is the same as the primary language.

## Launcher Commands

These commands are used to control the Ren'Py launcher from the command line.

### Generate GUI

Generates a GUI for an existing Ren'Py game.

    ./renpy.sh launcher generate_gui <basedir> [options...]

    .\lib\py3-windows-x86_64\python.exe renpy.py launcher generate_gui <basedir> [options...]

--width <width>
  Default:

    1280

  Specifies the width of the generated gui.

--height <height>
  Default:

    720

  Specifies the height of the generated gui.

--accent <color>
  Default:

    #00B8C3

  Specifies the accent color used throughout the gui.

--boring <color>
  Default:

    #000000

  Specifies the boring color used for the gui background.

--light

  Considers this a light theme.

--template <directory>
  Default:

    "gui"

  Specifies the template directory containing source code.

--language <language>
  Default:

    None

  Specifies the language to translate strings and comments to.

--start

  Starts a new project, replacing images and code.

--replace-images

  Overwrites existing images.

--replace-code

  Overwrites existing gui.rpy file.

--update-code

  Updates existing gui.rpy file.

--minimal

  Only updates option.rpy and translations.

### GUI Images

Generates images (e.g. for buttons, bars, radio buttons, etc) based on GUI variables.

    ./renpy.sh launcher gui_images <basedir> [options...]

    .\lib\py3-windows-x86_64\python.exe renpy.py launcher gui_images <basedir> [options...]

### Get Projects Directory

Prints the directory that the Ren'Py launcher uses to store projects.

    ./renpy.sh launcher get_projects_directory

    .\lib\py3-windows-x86_64\python.exe renpy.py launcher get_projects_directory

### Set Projects Directory

Sets the directory that the Ren'Py launcher uses to store projects. It's intended for use on minimal systems where none of the options for selecting a projects directory are available.

This can only be done when the launcher is not running.

    ./renpy.sh launcher set_projects_directory <projects>

    .\lib\py3-windows-x86_64\python.exe renpy.py launcher set_projects_directory <projects>

<projects>

  Specifies the path to the projects directory.

### Set Project

Sets the current project to the given project. This will change the projects directory and currently selected project in the launcher to accomplish this goal.

This can only be done when the launcher is not running.

    ./renpy.sh launcher set_project <project>

    .\lib\py3-windows-x86_64\python.exe renpy.py launcher set_project <project>

<project>

  Specifies the full path to the project to select.

### Update Old Game

Copies .rpyc files from `<basedir>/game` to `<basedir>/old-game`.

    ./renpy.sh launcher update_old_game <basedir>

    .\lib\py3-windows-x86_64\python.exe renpy.py launcher update_old_game <basedir>

See also

- The Old-game Directory

## Custom Commands

In addition to the commands defined above, it is possible to create commands for a particular project using `renpy.arguments.register_command()`.

When running a command, the game will first initialize, then run the command.

renpy.arguments.register_command(name, function, uses_display=False)

  Registers a command that can be invoked when Ren'Py is run on the command line. When the command is run, function is called with no arguments.

  name
    Type:

      str

    Specifies the name of the command in the interface.

  function
    Type:

      function

    Specifies the function that is called when the command is run. function is called with no arguments.

    If function needs to take additional command-line arguments, it should instantiate a `renpy.arguments.ArgumentParser`, and then call `parse_args()` on it. Otherwise, it should call `renpy.arguments.takes_no_arguments()`.

    If function returns True, Ren'Py startup proceeds normally. Otherwise, Ren'Py will terminate when `function()` returns.

    See also

    For more information about command line parsing, look at the ArgumentParser documentation.

  uses_display
    Type:

      bool

    If True, Ren'Py will initialize the display. If False, Ren'Py will use dummy video and audio drivers.

### Example

    init python:

        def compute_area_command():
            ap = renpy.arguments.ArgumentParser(description='Compute the area of various shapes.')
            ap.add_argument("dimensions", nargs="*", type=float, help="The dimension of the shape.")
            ap.add_argument("--square", action="store_true", help="If given, compute the area as a square.")
            ap.add_argument("--rectangle", action="store_true", help="If given, compute the area as a rectangle.")
            ap.add_argument("--circle", action="store_true", help="If given, compute the area as a circle.")

            args = ap.parse_args()

            if args.square:
                print(f"Square: {args.dimensions[0] ** 2}")

            elif args.rectangle:
                print(f"Rectangle: {args.dimensions[0] * args.dimensions[1]}")

            elif args.circle:
                print(f"Circle: {3.14 * args.dimensions[0] ** 2}")

            # Terminate and do not run Ren'Py normally
            return False

        renpy.arguments.register_command("compute_area", compute_area_command)

The command can then be called as follows:

    > ./renpy.sh <basedir> compute_area 3 --square

    Square: 9.0

    > ./renpy.sh <basedir> compute_area 3 2 --rectangle

    Rectangle: 6.0

    > ./renpy.sh <basedir> compute_area 1 --circle

    Circle: 3.14

    > ./renpy.sh <basedir> compute_area --help

    > .\lib\py3-windows-x86_64\python.exe renpy.py basedir compute_area 3 --square

    Square: 9.0

    > .\lib\py3-windows-x86_64\python.exe renpy.py basedir compute_area 3 2 --rectangle

    Rectangle: 6.0

    > .\lib\py3-windows-x86_64\python.exe renpy.py basedir compute_area 1 --circle

    Circle: 3.14

    > .\lib\py3-windows-x86_64\python.exe renpy.py basedir compute_area --help