Overview
While you can build and update flows directly in the Persona Dashboard, the Persona CLI provides a way to manage your configuration in a way that is purpose-built for agentic AI coding tools like Claude, ChatGPT, etc.
Using the CLI, every resource in your organization, such as Inquiry Templates, Workflows, Verification configurations, Themes, and Transactions, is serialized into YAML files in a Git repository hosted by Persona. This allows AI agents (or your developers) to easily read, edit, and manage your identity operations as version-controlled code. Pushing changes to the Persona-hosted repository makes the configurations live on the Dashboard, but you can also seamlessly store and maintain these files alongside your other infrastructure-as-code (IaC) in GitHub, GitLab, or similar systems.
Key Benefits
- AI-first design: The Persona CLI is built entirely to work seamlessly with agentic AI coding tools. The CLI automatically installs an agent harness and builder skills into your repository so AI agents understand exactly how to find resources, edit them safely, and run CLI commands.
- Infrastructure-as-Code (IaC) compatibility: By treating your Persona configuration as code, you can store, manage, and review it alongside your existing backend infrastructure in GitHub, GitLab, or other version control systems.
- Dashboard parity & resource management: The CLI goes beyond just configuration edits. You can browse and view records, publish templates, and perform most of the actions typically done via the Dashboard, directly from your terminal.
- Built-in version control: Your configuration is automatically versioned by Git SHA references, allowing you to easily track exactly what changes were made, when, and by whom (or which AI).
- Bi-directional sync: Changes made through the Dashboard are immediately reflected in your YAML files as a new commit. New commits pushed to the Persona-hosted repository are immediately available on the Dashboard, allowing you to push your changes and verify them visually.
Getting Started
-
Install the CLI
The Persona CLI is available via npm. To install it globally on your machine, run the following command in your terminal:
npm install -g persona-cli@latest(You can verify your installation anytime by running
persona --version) -
Authenticate
Log in to your Persona account using the CLI. This uses an end-user OAuth flow:
persona login(You can check your active session with
persona whoamior sign out usingpersona logout) -
Initialize your repository
Create an empty directory for your configuration, then initialize it:
mkdir persona-config && cd persona-config persona initDuring initialization, you will be asked if you want to set up the repository for AI agents. We highly recommend answering
yto this prompt. Doing so installs the necessary AI agent guides (likeCLAUDE.mdandAGENTS.md) into the directory. Without this setup, AI tools like Claude or Codex will not know how to correctly interact with your configuration files.Your new repository will mirror your organization’s resources, with specific directories for
inquiry-templates/,workflows/,themes/, and more.
The Core Workflow
Once initialized, managing your configuration follows a simple loop:
- Pull the latest: Run
persona config pullto fetch the latest server state and avoid editing stale configuration. - Edit: Prompt your AI coding agent to make changes to the YAML files (or edit them manually).
- Lint: Run
persona config lintto validate the YAML syntax of your changed files. - Commit: Run
persona config commit -y -m "Persona CLI: <description>"to save your changes locally. - Push: Run
persona config push -yto publish your commits to Persona, where they are immediately applied.
Tip: After a push, you can use persona state to find a resource’s token, and persona deeplink <token> to generate a direct Dashboard URL to view your changes.
Frequently Asked Questions (FAQ)
What configuration is supported?
You can manage core Persona objects like Inquiry Templates, Workflows, and Transactions. The easiest way to see exactly what is supported is to explore the CLI help pages by running persona -h or searching for specific actions using persona cmd search <words>.
Are the CLI commands stable?
Yes, we intend to keep most commands as stable as possible. Backwards-incompatible changes will only be introduced if absolutely necessary. CLI updates are published regularly, so be sure to update your local installation to access new features.
Can I add the Persona CLI to automated build pipelines?
The standard persona login relies on an end-user OAuth flow. A dedicated Machine-to-Machine (M2M) OAuth flow is currently in development to officially support CI/CD pipelines. If you need immediate assistance integrating the CLI with automated build pipelines, please reach out to your Persona contact.
How do I request a new feature or report an issue?
We are actively building new functionality for the CLI and are taking feature requests. If something is not working well or you want to request a feature, please reach out to your Persona contact through your established communication channels.