Skip to content

Usage

Have you tried the tutorial?

If you haven't already, start with the tutorial to get a quick overview of how to use Alchemist. The tutorial will guide you through the process of setting up Alchemist, preparing the project, analyzing your sources, and generating reports.

Alchemist is a command line tool that can be used to analyze and convert legacy code. The usage is the same for all supported platforms, except for the path to the executable.

All of the command samples in the documentation use alchemist, but you'll need to use the correct path to the executable for your platform as described in the next section.

We never access any of your data

Alchemist is a code and xml static analysis & conversion tool. It never access any data. It is designed to run locally on your machine. We only access internet to verify your license (and may even run entirely without internet access using offline license).

CLI Built-In Help

Alchemist has built-in help that can be accessed by running alchemist -h or alchemist <command> -h. The built-in help is the most up-to-date source of information about Alchemist CLI.

First Run

In order to use Alchemist, you will need to activate your license key or offline license file.

To provide the license key, run the following command and you will be prompted to enter your license key: 

alchemist license

How to run Alchemist?

You can run Alchemist from command prompt or PowerShell.

  • Launch the Command Prompt or the PowerShell app
  • Use C:\Program Files (x86)\Alchemist\Alchemist\alchemist as executable path (assuming you didn't specify a custom folder during the installation).
  • Launch the Terminal app on your Mac under Application -> Utilities -> Terminal or by searching for Terminal in Spotlight.
  • Use /Applications/Alchemist/alchemist as executable path.

Acquiring Offline License

Offline license may be necessary if your machine has no internet connection or is behind a firewall, which prevents Alchemist from connecting to the license server.

In order to get an offline license, run the following command: 

alchemist license offline

You will be prompted to enter your license key, and then the special link will be provided. Visit this link (sign-up or sign-in may be necessary) to download offline license file. The license is "locked" to machine, where alchemist license offline command was run, so it does not matter from which machine you visit the site, just be sure to transfer license file to machine where you run alchemist, then install it using the following command: 

alchemist license -f /path/to/license/file

You can download offline license file with single license key for up to 3 different machines. Please follow steps above for all of them.

Refresh License

If your license features have been changed, you have to force license reactivation to refresh cached license files on your machine.

This command can only be applied to an online license. To reissue an offline license, please use the license offline command. 

alchemist license refresh

Obtain Source Lock File

If your license bundle includes source restriction, Alchemist will require source lock file to figure out which files are allowed for analysis. To obtain the source lock file, please contact us. Once you have it on your system, activate it using license command. 

alchemist license -l /path/to/source_lock.json

Reset License

In order to reinstall an online license, you have to reset your license first, then use alchemist license command to install a new one. 

alchemist license reset

Standard Usage Pattern

We recommend creating a separate folder for alchemist sources and results and use a distinct project name when running any operation.

Note

You must have permissions to write files to the aforementioned folder.

Place all source files in subfolder called src and create a folder for outputs out.

Retain original folder structure for sources

The way your code and other sources is organized on the server may provide important insights and help identify owners. Thus we highly recommend retaining the original folder structure inside the src folder.

For more details see how to prepare folder structure.

Check out additional instructions on preparing sources in dialects documentation.

Perform desired operation by running alchemist from the base folder with the following command: 

alchemist <operation> -o out -p your_project_name src
Where operation is one of: analyze or convert.

Tip

You can pass multiple paths at the same time, e.g.: 

alchemist <operation> -o out -p your_project_name path/to/src1 another/src2 one/more/file.ext

Running UI

You can run Alchemist UI by adding the -u flag, e.g.: 

alchemist analyze src -u path/to/sources