Last updatedNov 18, 2019

Step 1: Set up Forge

To start using Forge, you’ll have to create an Atlassian developer site, install the Forge CLI, and log in with an Atlassian API token.

Before you begin

Read and understand the limitations

Make sure you read and understand the Beta limitations before starting development.

Install and configure the required software

To complete this tutorial, you need to install the following.

  • Node.js (a Node 12 version from 12.12.0 or later). Installing Node.js also installs npm.
    • Important: We recommend running Node under your user. If you're running node under root privilege instead, you'll need to update the Node configuration to allow global module installs using binaries by running:
      npm config set unsafe-perm true
    • To check your Node version, run the following in the terminal:
      node --version
    • To update your Node version, we recommend using the Node Version Manager (nvm):
  • Python (a Python 2 version from 2.6.0 or later). The CLI is not compatible with Python 3.
    • To check your setup, run the following in terminal:
      python --version
      If the output is a Python 2 version later than 2.6.0, then your setup is correct. If not, you need to set the variable PYTHON with the path to your python installation when you run the command to install the CLI. For example, if the path is python2.6 then you install the CLI by running:
      PYTHON=python2.6 npm i -g @forge/cli
  • Libsecret. Only required on Linux.
  • Windows tooling and configuration. Only required on Windows.
    • Option 1: Use Microsoft's windows-build-tools to install the required tools and configurations.
      1. Open an elevated PowerShell.
      2. Install the tools and configurations by running the following, as Administrator:
        npm install -g windows-build-tools
    • Option 2: Manually install dependencies and configuration.
      1. Install Visual C++ Build Environment: Visual Studio Build Tools (using "Visual C++ build tools" workload) or Visual Studio 2017 Community (using the "Desktop development with C++" workload)
      2. Launch cmd and set the configuration by running:
        run npm config set msvs_version 2017

Set up an Atlassian Cloud developer site

Create a developer site where you can install and test your app. The developer site has Confluence and all of the Jira applications installed.

The limits on the numbers of users you can create are as follows:

  • Jira Software and Jira Core: 5 users
  • Jira Service Desk: 1 agent
  • Confluence: 5 users

Create an Atlassian Cloud developer site

  1. Go to and create a site using the email address associated with your Atlassian account.
  2. Once your site is ready, log in and complete the setup wizard.

Install the Forge CLI

Install the Forge CLI using npm. You’ll install the CLI globally so that the commands can be run across your system.

  1. Install the Forge CLI globally by running:
    npm install -g @forge/cli
  2. Verify that the CLI is installed correctly by running:

    forge --version

    You should see the version number reported in the terminal:


    If a version number is not shown then the installation failed. Repeat step 1 and look for errors reported in the terminal.

Log in with an Atlassian API token

Create or use an existing Atlassian API token to log in to the CLI.

Create an Atlassian token

The CLI will use your token when running commands.

  1. Go to
  2. Click Create API token.
  3. Enter a label to describe your API token. For example, forge-api-token.
  4. Click Create.
  5. Click Copy to clipboard and close the dialog.

Log in to the Forge CLI

You need to log in to start using Forge commands:

  1. Start the process by running:
    forge login
    Note, you’ll need gnome-keyring to perform this step on Linux.
  2. Enter the email address associated with your Atlassian account.
  3. Enter your Atlassian API token. You copied this to the clipboard in step 5.

You will see a message similar to this confirming you are logged in:

✔ Logged in as Sam Kim

Next step

See Step 2: Create a Hello World app to create and install a simple app.