> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useparagon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started with Paragraph

> Paragraph allows you to author and maintain Paragon integrations as code, which can be synced with a Git repository to track revisions over time.

<Frame>
  <img src="https://mintcdn.com/paragon/jCM_Y_j0HttScr1R/assets/Frame%201000002911%20(2).png?fit=max&auto=format&n=jCM_Y_j0HttScr1R&q=85&s=4180d3540d8e5a92827bed8d4ba18350" alt="Page cover image" width="1619" height="438" data-path="assets/Frame 1000002911 (2).png" />
</Frame>

With Paragraph, your engineering team can:

* Define all your integrations powered by Paragon as code, while still being able to view, edit, and debug from the dashboard
* Version control all changes to your integrations in a Git repository, which can be used to bring code review, unit testing, and CI/CD to your development process
* Use more advanced abstractions in Workflows, including reusable steps or modularizing workflow logic across integrations

<Frame>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/eD2a7LlCjQM?si=yZFNML9EjvuzK5Dq" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
</Frame>

## Overview

Paragraph is a TypeScript-based framework for building your Paragon integrations in code. In a Paragraph project, you'll define:

* Integrations that are available to your users
* [Connect Portal configuration](/connect-portal/connect-portal-customization), including [User Settings](/connect-portal/workflow-user-settings) and [Field Mappings](/connect-portal/field-mapping)
* [Workflows](/workflows/building-workflows), including [Triggers](/workflows/triggers) and Steps

Paragraph projects can be packaged and sent to Paragon for deployment using the Paragon CLI or [from your CI/CD](/paragraph/setting-up-git-sync).

You can also continue to use the Paragon dashboard to edit your projects. By [setting up Git Sync](/paragraph/setting-up-git-sync), you can sync back changes made in the Paragon dashboard to your Paragraph project, stored in a Git repository.

<Accordion title="What Isn't Defined in a Paragraph Project?">
  Paragraph represents your integration business logic and doesn't include some types of configuration values that are specified in the dashboard.

  The following configuration values must be maintained using the dashboard and will have no representation in your Paragraph project:

  * [Environment Secrets](/workflows/environment-secrets): Sensitive values that are used in Workflows are defined and managed in the dashboard, in Project Settings.

  * [Signing Keys](/getting-started/installing-the-connect-sdk#setup-with-your-own-authentication-backend): The private key used to sign Paragon User Tokens is generated and managed in the dashboard, in Project Settings.

  * [Client ID and Secret](/getting-started/adding-an-integration#connect-your-developer-app-to-paragon): Any sensitive credentials representing your OAuth app with an integration are managed in the Settings tab of any integration.

  * Scopes: Scopes requested by your OAuth app are also managed in the Settings tab of any integration.

    * For Custom Integrations, scopes are included in the Paragraph config file.

  * [Team Members](/managing-account/teams): Users and roles that have access to your Paragon organization are managed in the dashboard, in Organization Settings.
</Accordion>

## Installing the CLI

### Installing the CLI and Authorizing Your Account

To begin setting up Paragraph project, you'll need to install the Paragon CLI. You can install the CLI globally with npm:

```bash theme={null}
npm install -g @useparagon/cli
```

Once installed, the CLI will be available as the alias `para`. See for the full reference for available CLI commands.

You can link your Paragon account to the CLI by running:

```bash theme={null}
para auth login
```

<Accordion title="Using an On-Prem Environment?">
  You can authenticate to the CLI from your on-premises environment with the `--host` flag:

  ```bash theme={null}
  para auth login --host https://dashboard.yourhost.paragon.so
  ```
</Accordion>

Follow the CLI prompt to login to Paragon and authorize the CLI. When you successfully log in, you should see:

```bash theme={null}
Logged in as [Your Name] (yourname@email.com)
```

Authenticating with the CLI generates a CLI Key which is stored locally in `~/.paragon/credentials.json`. You can view and revoke CLI Keys in the dashboard in; **Settings > CLI Keys**.

## Starting a Paragraph Project

### Exporting from Paragon

You can export a Paragraph project from your Paragon dashboard by using the CLI:

```bash theme={null}
para init --create-from-existing
```

A project selector will appear to choose a project to export as a Paragraph project.

### Initializing an Empty Project

Alternatively, you can initialize a new Paragon project with the CLI:

```bash theme={null}
para init new-project-name
```

### Cloning an Existing Project

If you are cloning an existing Paragraph repository that a teammate started, make sure to install dependencies in the project:

```bash theme={null}
git clone git@github.com:useparagon/integrations.git
para install
```

## Creating a New Integration

Create a new integration in Paragraph with the CLI:

```bash theme={null}
para new integration
```

A prompt will appear to select the integration you'd like to add. Once selected, a new folder for the integration will appear in your `src/` folder.

*Learn more about how to configure an integration in *[*Defining Integrations*](/paragraph/defining-integrations)*.*

## Creating a New Workflow

Start building a new workflow in an existing integration with the CLI:

```bash theme={null}
para new workflow --integration salesforce
```

Specify the name of the integration folder, e.g. `salesforce` in the `--integration` flag. A prompt will appear to title the workflow. A new TypeScript file will appear in the `src/integrations/[integration]` subfolder.

*Learn more about workflows and how to define and orchestrate steps in *[*Defining Workflows*](/paragraph/defining-workflows)*.*

## Building and Pushing

Once you are ready to push your changes back to the Paragon dashboard, you can use the CLI to validate your project and push to Paragon:

```bash theme={null}
para build
```

*Learn more about handling build errors in *[*Build and Push*](/paragraph/build-and-push)*.*

Once you see a message confirming that a build has been created, use the CLI to upload to the Paragon platform:

```bash theme={null}
para push
```

<Info>
  Try [Git Sync](/paragraph/setting-up-git-sync) to configure an integration between your Paragraph files stored in a Git repository and your Paragon project.

  Git Sync keeps your Paragon project and Paragraph repository automatically in-sync.
</Info>