Respresso CLI commands and options reference

The Respresso CLI comes with 3 major commands:

• respresso init: Checks the current and all the sub-directories for projects (currently, Android and iOS) and tries to auto create the respresso.json config file for you. In case there is no project found you can create an example config file to get started quickly.
• respresso sync: Automatically updates your synced files based on your respresso.json config files. Creates or updates your respresso.lock file if necessary.
• respresso clean: Removes all the downloaded files (based on the respresso.lock file) and removes the respresso.lock file. Your config won't be affected.

To get a quick info about these commands and their options, you can use the respresso help <command> or respresso <command> --help commands. In addition to this, you can list all the global options with the respresso help or respresso --help commands.

The respresso init command

Creates a respresso.json file in the current directory.
You should only run this command when you first setup your Respresso sync for the current project. Further changes should be made in the respresso.json config file. To understand the config, take a look at the get started and the CLI config reference pages.

When you run the respresso init command, it will scan the current and all the sub-directories to detect projects. In case it finds at least one, it will prompt you to select from the discovered ones, and it will automatically generate a config for you.
If it does not discover any projects, it will prompt you to select from a simple or advanced config examples, and it will save it.

Currently, the CLI can discover only simple Android, iOS and Web (or NodeJs) projects. It does its best to help you configure the project, but you should always check the generated config manually.

Set default project token

You can use the --token <token> option to set the default token for discovered projects. (Example configs won't use this token.) If only one project is discovered, then it will automatically use the provided token, otherwise you will need to select which project should use it.

This allows a streamlined config creation for a single module (or project) in one command:
respresso init --token <token>

Generate an advanced example config

You might want a quick example to help you configure your project without digging through the docs. This is why the respresso init --example generates a config file that showcase almost all the options.

Keep in mind, that the resulting file can't be used to execute a sync, instead it helps you understand the available options and includes multiple common examples.

The respresso sync command

Update local resource files with your connected Respresso projects' converted resource files.
You need to run this command each time you want to make sure that the resource files are up-to-date.

The sync needs a respresso.json config file to execute. It will use the respresso.lock file if it exists. If the sync executes successfully, it will make sure that the respresso.lock file is up-to-date and consistent with the file system.

When you execute the sync command, the following file operations will be executed:

• Unnecessary files will be removed. (Only those, that were once written by the CLI, tracked in respresso.lock. If the lock file can't be loaded (corrupted or deleted) all the files will remain untouched.)
• Any files that exists, but need to be moved due to a change in target overrides will be moved to the desired location.
• All tracked files will be hash compared with the Respresso server's version and will be overridden if not matching. All manual changes will be overridden. Not existing files will be downloaded and created.
• If any file operation requires creation of a directory, it will be automatically created. The created directories won't be cleaned up by the CLI.

Don't forget to check the global options that can be used with this command too.

Local sync and offline mode

The respresso.lock file contains hashes, original and local path of the downloaded files and some meta info of the version. This allows the CLI to check if the local files are the same as on the server without making a single request.

If all the requested files are present and the hash is matching, then there is no need to sync with the server*. In this case, the sync can be done locally. The file moves are required by modified target overrides, it will execute them without network requests.

*The sync will compare version e-tags with the server even if the local files are up-to-date to detect remote changes. This step is skipped when the requested versions are not dynamic and the synced versions are all finalized. If the etag comparison fails with a network error (e.g. your machine is offline), it will fall back to offline mode and treat the error as if the server responded with the same e-tags.

Sync only one or a subset of projects

The sync command has a --only-project <project name or token> option that can be used multiple times. This comes handy, when you have a multi-module project where each module is a separate Respresso project, and you want to update only one or a subset of projects that you are working on.

E.g. to sync only two projects, you can use a command similar to this:
respresso sync --only-project core-module --only-project auth-module

Sync in other directory

If you choose to have a separate config file for each module of a project, you can sync each (one-by-one) from the root directory using the --directory <path> option.

To execute the sync in a subdirectory - where the respresso.json config is located -, you can use the following command:
respresso sync --directory ./path-to-module-directory

Force enable/disable strict mode

Strict mode comes handy when you want to ensure your build is repeatable. But, read-only versions are not a thing you want to enforce during development.

This is why the strict property in the config defaults to false and the CLI provides the --[no-]strict flag that overrides the config value.

To execute the sync in strict mode - probably during release builds on a CI - you can use a command similar to this:
respresso sync --strict

The respresso clean command

Remove all local resource files and the lock file. (All directories will remain, those are not cleaned up.)
When you execute the clean command, it will remove all the files tracked by Respresso in the respresso.lock file. If you don't have a valid lock file, then the command won't remove any files, or it will fail.

Sometimes, you might want to force re-download everything. To do so, you need to execute the clean and then the sync command.

Clean in other directory

Similarly to the sync, the clean command also has a --directory <path> option.

To execute the clean in a subdirectory - where the respresso.json config is located -, you can use the following command:
respresso clean --directory ./path-to-module-directory

Please note that, this will clean up all the files from the lock file, the directory option is not a filter, it only changes the working directory.

Don't forget to check the global options that can be used with this command too.

Global options and flags

These options and flags can be used with each command. The CLI can also list these with the respresso help command.

Help

You can print the usage of the CLI or any of the commands using the --help flag, or you can use the -h shorthand. This is the same as running respresso help <command>.

Log level

By default, the CLI uses the info log level, that prints some useful information during execution. You can use the --log-level <level> option or the -l <level> shorthand to change this.

These are the available log levels:

1. debug: Prints all information that can help debug any issues. You can use this if you don't understand what the CLI is doing. E.g.: you want to debug the target overrides. This will also log each request the CLI makes to the server.
2. info: Default log level. Prints useful information.
3. warn: Prints only warnings and higher level logs. Contains warnings that should be noted by the user of the CLI.
4. error: Prints only errors and higher level logs. Contains all errors, even if they don't cause the CLI to fail.
5. fatal: Prints only the fatal errors. This prints only the reason why the CLI failed to execute.

Disable interactivity

The CLI might prompt user input. E.g.: confirmation of file override of an untracked file. This may cause problems when you run it using automated systems or scripts. To disable these features, you can use the --no-interactive flag.
Please note that, this can cause unsafe operations to be executed without supervision.

Disable output colors

For compatibility reasons, the CLI supports disabling output coloring using the --no-color flag.

Disable file locking

The CLI tries to make sure that all the necessary file operations will succeed before executing them. For this, it opens and locks all the affected files. This works fine if your OS and file system supports it and makes the file operations safer.

Unfortunately, there are limitations on how many files can be open at the same time. In normal scenarios, you won't reach these, but for very large projects synced on MacOS can reach this limit. To get rid of that error, you can disable the file locking mechanism using the --no-file-locking.

If you disabled file locking and still getting a Too many open files - OS error or similar, you might increase the OS limit to at least 100. This is necessary, as the CLI has a hard coded concurrency limit of 100 concurrent file operations in place.