Archy Installation

This page goes through the steps necessary to get Archy set up and running on a machine. There is a prerequisites section where we'll make sure that your Genesys Cloud organization is set up correctly first, and then we'll go through Archy installation steps on different operating systems.

Before you install and run Archy for the first time, we need to make sure you have set up an OAuth client in your Genesys Cloud organization that Archy can use for authentication when it runs. You can also use a Genesys Cloud authorization token with Archy and if you're planning to do that, feel free to skip this step and go to the Installation section. If you're not sure, it's easiest to create an OAuth client to start off, and you can always switch over to use an authorization token later if you'd like.

The Genesys Cloud Resource Center is a great source of Genesys Cloud information and this page shows how to create an OAuth client. You'll want to create an OAuth client that Archy can use. Be sure to configure the OAuth client with the following settings:

• Token duration -> 86400 seconds ( recommended )
• Grant Type -> Client Credentials
• Roles on the Roles tab. The roles are what gives the OAuth client permissions in your organization.

The Architect permissions overview Resource Center page discusses permissions needed for Architect which should be used here as well. It's documented in Architect Scripting, but it's important remember that the OAuth client needs the architect:ui:view permission since that's needed to use Architect Scripting itself and that's part of Archy.

    Once you've created an OAuth client with the client credentials grant, you will
    want to save off the client id and client secret as you'll need them later.

The same basic procedure is used when installing Archy on a Linux, macOS or Windows machine. While we have more detailed instructions below, it's really just this:

• Create a directory where you want to install Archy.
• Download the Archy zip file appropriate for your operating system.
• Extract it to the directory you created above.
• ( highly recommended ) Add the directory you created above to your environment's path so you can run the archy script / batch file from any directory.

Please refer to the section appropriate to your operating system to see detailed instructions on setting Archy up.

• macOS/Linux Install
• Windows Install

Follow these steps to install Archy on macOS or Linux:

1. Create a directory where you want to install Archy. We recommend creating an archy directory in your user's home directory. To do so, open a terminal and run these commands:

$>  cd ~
$>  mkdir archy

2. Download the Archy installation .zip file appropriate for your operating system:
• Archy for macOS
• Archy for Linux
3. Unzip the contents of the downloaded zip file to the directory from step #1.

<br> To extract the zip via terminal command line:

# Assuming the archy-macos.zip file is in your `~/Downloads` directory
$> unzip ~/Downloads/archy-macos.zip -d ~/archy

<br> To extract the zip via Finder:

• Go to the download location of the archy-macos.zip
• Double click the archy-macos.zip file which will then create a new folder in the directory named archy-macos
• Go into the archy-macos folder and copy the contents
• Go to the ~/archy directory you created above and paste the items

<br>

After unzipping the file, the contents of the directory look like this:

~/archy/                     <-- directory from step #1
    archy                    <-- when running Archy, you will run this script file
    archyBin/                <-- directory that holds locally installed Archy executable versions
        archy-macos-2.33.1    <-- the Archy executable included in the zip installation file
              or                 the version will change over time as the Archy installation
        archy-linux-2.33.1        zip file is upgraded

<br>

4. Open a new terminal window and change directories to the directory you created in step #1.

At the command line lets run the version command by entering archy version to get Archy to output current version information:

$> cd ~/archy/
$> ./archy version
2.33.1

<br>

Note: If you are on macOS and you receive this error:

“archy-macos-2.33.1” cannot be opened because the developer cannot be verified.
macOS cannot verify that this app is free from malware.

To fix on macOS 13 (Ventura) and above, use the following instructions:

• Click the Cancel button.
• Open the System Settings app on your Mac.
• Open the Security & Privacy settings.
• Scroll to the Security section, and there should be an "archy-macos-2.33.1" was blocked from use because it is not from an identified developer. Click the Allow Anyway button.
• Go back to your terminal, and run ./archy version. Select Open in the dialog window. It should now correctly output the version number.

To fix in versions prior to macOS 13 (Ventura), use the following instructions:

• Click the Cancel button.
• Open the System Preferences app on your Mac.
• Open the Privacy & Security settings.
• Under the General tab, there should be an "archy-macos-2.33.1" was blocked from use because it is not from an identified developer. Click the Allow Anyway button to the right.
• Go back to your terminal, and run ./archy version. It should now correctly output the version number.

5. While this step is not required, we highly recommend that you go ahead and add the directory created in step #1 to the Unix PATH. This will make it so you can type archy in a terminal window without having to specify the full path to the archy script file or use ./archy every time you want to run Archy. In Unix, it depends on which shell you're running. We have steps for both bash and zsh below.

<br>

For bash:

• Open ~/.bash_profile in a text editor.
• Add the directory created in Step #1 to the PATH. Assuming we created an archy directory underneath our user's home directory (i.e. ~/archy), we'd add these lines:

# Adding the directory where Archy was installed to the PATH
export PATH="~/archy:${PATH}"

• Save the changes to the bash_profile file.

Now to test that this worked:

• Open a new terminal window.
• Make sure you're not in the ~/archy directory and enter archy version and press enter:

$> archy version
2.33.1

<br>

For zsh:

• Open ~/.zshrc in a text editor.
• Add the directory created in Step #1 to the PATH. Assuming we created an archy directory underneath our user's home directory (i.e. ~/archy), we'd add these lines:

# Adding the directory where Archy was installed to the PATH
export PATH=$PATH:~/archy

• Save the changes to the .zshrc file.

Now to test that this worked:

• Open a new terminal window.
• Make sure you're not in the ~/archy directory and enter archy version and press enter:

$> archy version
2.33.1

Great! You can now run Archy from any directory without having to specify the full file path to the archy script file.

<br>

You're donezies.

<br>

If there was a problem in Step #5:

• You can see what the Unix PATH looks like by issuing this command in the new terminal window:

echo $PATH

• If you see the ~/archy directory in the path, make sure the archy script file is executable by giving the archy script file executable permissions:

~/archy> chmod +x archy

• Similarly, you can also make sure that the versioned Archy executable contained in the downloaded .zip file is also executable. Change directories to the archyBin subdirectory and issue a similar chmod command on the Archy executable too. For example:

~/archy/archyBin> chmod +x archy-macos-2.33.1
or
~/archy/archyBin> chmod +x archy-linux-2.33.1

Follow these steps to install Archy on Windows:

1. Create a directory where you want to install Archy. For this install, we'll install Archy in C:\Users\MyUser\archy.

To do so, open a command and run these commands:

C:\WINDOWS\system32> cd %USERPROFILE%
C:\Users\MyUser> md archy

2. Download the Windows Archy installation .zip file:
• Archy for Windows
3. Unzip the contents of the downloaded zip file to the directory from step #1. After unzipping the file, the contents of the directory look like this:

C:\Users\MyUser\archy\         <-- directory from step #1
    archy.bat                  <-- when running Archy, you will run this batch file
    archyBin\                  <-- directory that holds locally installed Archy executable versions
        archy-win-2.33.1.exe    <-- the Archy executable included in the zip installation file

4. Open a new terminal window and change directories to the directory you created in step #1. At the command line lets run the version command by entering archy version to get Archy to output current version information:

C:\Users\MyUser\archy> archy version
2.33.1

5. While this step is not required, we highly recommend that you go ahead and add the directory created in step #1 to the PATH environment variable. This will make it so you can simply type archy in a command window without having to specify the full path to the archy batch file every time you want to run Archy.

To do so:

• On the Windows desktop, right click on My Computer.
• In the popup menu, select Properties.
• Select the Advanced tab on the System Properties window.
• Click on Environment Variables
• Under System Variables ( or User Variables for just the current user ), edit the Path variable and add the full path to the directory created in Step #1. For example, if Archy was installed to C:\Users\MyUser\archy, you could add the directory to the path by appending ;C:\Users\MyUser\archy to the current Path value.
• Click OK to save the change.

Now to test that this worked:

• Open a new command window.
• Make sure you're not in the directory created in Step #1 and enter archy version and press enter:

C:\WINDOWS\system32> archy version
2.33.1

Congrats - you can now run Archy from any directory without having to specify the full file path to the archy batch file. Yea!

If there was a problem:

• You can see what the Windows PATH variable looks like by issuing this echo command in the new command window:

C:\WINDOWS\system32> echo %Path%

Note:  Remember that if you're running something other than the standard command window like PowerShell,
the command to show the Path environment variable value could use a different syntax.

Verify that directory from Step #1 is in the Windows Path. Or additionally, you can try using where to see which archy Windows is using. We want it to be using the archy.bat file in the directory from Step #1 such as C:\Users\MyUser\archy\archy.bat. This is the command you'd execute to see: and enter archy version

C:\WINDOWS\system32> where archy

<br>

Now, let's go over the process for setting up Archy for a Genesys Cloud organization.

Archy - Ver. 2.33.1, generated on January 3, 2025