Paragraph allows you to author and maintain Paragon integrations as code, which can be synced with a Git repository to track revisions over time.
With Paragraph, your engineering team can:
Paragraph is a TypeScript-based framework for building your Paragon integrations in code. In a Paragraph project, you’ll define:
Paragraph projects can be packaged and sent to Paragon for deployment using the Paragon CLI or from your CI/CD.
You can also continue to use the Paragon dashboard to edit your projects. By setting up Git Sync, you can sync back changes made in the Paragon dashboard to your Paragraph project, stored in a Git repository.
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: Sensitive values that are used in Workflows are defined and managed in the dashboard, in Project Settings.
Signing Keys: The private key used to sign Paragon User Tokens is generated and managed in the dashboard, in Project Settings.
Client ID and Secret: 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.
Team Members: Users and roles that have access to your Paragon organization are managed in the dashboard, in Organization Settings.
To begin setting up Paragraph project, you’ll need to install the Paragon CLI. You can install the CLI globally with npm:
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:
Using an On-Prem Environment?
You can authenticate to the CLI from your on-premises environment with the --host
flag:
Follow the CLI prompt to login to Paragon and authorize the CLI. When you successfully log in, you should see:
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.
You can export a Paragraph project from your Paragon dashboard by using the CLI:
A project selector will appear to choose a project to export as a Paragraph project.
Alternatively, you can initialize a new Paragon project with the CLI:
If you are cloning an existing Paragraph repository that a teammate started, make sure to install dependencies in the project:
Create a new integration in Paragraph with the CLI:
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.
Start building a new workflow in an existing integration with the CLI:
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.
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:
Learn more about handling build errors in Build and Push.
Once you see a message confirming that a build has been created, use the CLI to upload to the Paragon platform:
Try 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.
Paragraph allows you to author and maintain Paragon integrations as code, which can be synced with a Git repository to track revisions over time.
With Paragraph, your engineering team can:
Paragraph is a TypeScript-based framework for building your Paragon integrations in code. In a Paragraph project, you’ll define:
Paragraph projects can be packaged and sent to Paragon for deployment using the Paragon CLI or from your CI/CD.
You can also continue to use the Paragon dashboard to edit your projects. By setting up Git Sync, you can sync back changes made in the Paragon dashboard to your Paragraph project, stored in a Git repository.
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: Sensitive values that are used in Workflows are defined and managed in the dashboard, in Project Settings.
Signing Keys: The private key used to sign Paragon User Tokens is generated and managed in the dashboard, in Project Settings.
Client ID and Secret: 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.
Team Members: Users and roles that have access to your Paragon organization are managed in the dashboard, in Organization Settings.
To begin setting up Paragraph project, you’ll need to install the Paragon CLI. You can install the CLI globally with npm:
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:
Using an On-Prem Environment?
You can authenticate to the CLI from your on-premises environment with the --host
flag:
Follow the CLI prompt to login to Paragon and authorize the CLI. When you successfully log in, you should see:
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.
You can export a Paragraph project from your Paragon dashboard by using the CLI:
A project selector will appear to choose a project to export as a Paragraph project.
Alternatively, you can initialize a new Paragon project with the CLI:
If you are cloning an existing Paragraph repository that a teammate started, make sure to install dependencies in the project:
Create a new integration in Paragraph with the CLI:
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.
Start building a new workflow in an existing integration with the CLI:
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.
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:
Learn more about handling build errors in Build and Push.
Once you see a message confirming that a build has been created, use the CLI to upload to the Paragon platform:
Try 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.