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

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

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

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...]
<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

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

./renpy.sh <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...]
--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

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]
--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

Remove Persistent Data

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

./renpy.sh <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...]
<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...]
<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.

Examples:
./renpy.sh <basedir> test [<testcase>] [options...]
<testcase>

Specifies the name of the testcase or test suite to run. If not given, the "global" test suite will be run.

--enable_all

Executes all test cases and test suites, regardless of their enabled property.

--overwrite_screenshots

Overwrite existing screenshots when a screenshot statement is executed.

--hide-header

Disables the header at the start of the test run.

--hide-execution {no|hooks|testcases|all}

Hides information about test execution. --hide-execution hooks hides hooks, --hide-execution testcases hides test cases and hooks, and --hide-execution all hides everything.

--hide-summary

Disables the summary at the end of the test run.

--report-detailed

Shows detailed information about each test during the run.

--report-skipped

Shows information about skipped tests. This option should be used together with --report-detailed.

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

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...]
--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...]
--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>
<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>
<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...]
--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

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...]
<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...]

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...]
<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...]
<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...]
--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...]

Get Projects Directory

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

./renpy.sh 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>
<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>
<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>

See also

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