Skip to Content
PetavueHelp Center
Integrations Guide

Using Petavue from Claude Code or Codex

Petavue has a command-line tool that lets AI coding agents such as Claude Code and OpenAI Codex answer questions about your business data. Set it up once, then ask your agent about pipeline, workflows, and definitions the same way you'd ask an analyst.

Before You Start

  • A Petavue account with the admin role. Only admins can use the CLI.
  • Claude Code or Codex installed on your computer
  • Node.js 20 or later. The tool installs with npm, which comes with Node.js.

One-Time Setup

Setup takes three steps, and you only do it once.

1. Install the Petavue tool

Open a terminal and run:

npm install -g @petavue/cli
A terminal running npm install -g @petavue/cli, which finishes with a changed 1 package message
Installing the Petavue tool with npm

2. Log in with your API key

In Petavue, open My Profile and copy your key from the API Key field.

The My Profile page showing Full Name, Role set to admin, Email, and Password fields, with the API Key field highlighted at the bottom, its value masked and a copy button beside it
Your API key is on the My Profile page, with a button to copy it

Then log in one of two ways.

Option A: from your terminal

petavue login

Paste your API key when prompted.

A terminal running petavue login, prompting for the API key with the key masked, then confirming which account and tenant you are logged in as
Logging in from the terminal, with the key masked as you paste it

Option B: from inside Claude Code or Codex

The paste prompt doesn't work inside an agent, so give the key on the command line instead. Either tell your agent:

"Log me into Petavue with this key: sk_pv_…"

A Codex conversation where the user shares a masked API key and asks to be logged into the Petavue CLI, and Codex confirms the login with the verified account, tenant, role, and auth method
Asking your agent to log you in, shown here in Codex

Or, in Claude Code, run the command directly. The ! at the start runs it as a shell command from inside Claude Code.

! petavue login --token sk_pv_…

With Option B, your API key becomes part of the agent's conversation, so it's sent along with your chat and kept in the session history. Option A keeps the key out of the conversation, so use it when you can.

To check that you're logged in at any time:

petavue whoami

3. Teach your agent about Petavue

petavue skill install

This installs a small skill file that tells Claude Code and Codex what Petavue is and how to use it. It finds whichever supported agents you have installed automatically. To pick one yourself, add --claude or --codex.

A Codex conversation where the user asks Codex to install the Petavue skill, and Codex runs petavue skill install --codex and confirms where the skill was installed
You can also ask your agent to install the skill, and it runs the same command for you

That's it. Open Claude Code or Codex and start asking.

A Typical Conversation

Talk to your agent the same way you'd talk to an analyst. Include the details that matter: time period, region, product, metric, comparison.

1. Ask a question

"How did qualified pipeline perform this month compared with last month?"

Petavue works out where the answer lives, whether that's a workflow, a dashboard, or the underlying data, and your agent reports the answer back.

A Codex conversation asking how qualified pipeline performed this month compared with last month, with Codex choosing the Petavue skill, sending the question to Petavue, and starting a Petavue session
Your agent recognizes a business question and hands it to Petavue

2. Ask a follow-up

"Break that down by channel."

There's no need to repeat the time period or metric. The follow-up builds on the answer you just got.

Codex answering a follow-up to break the result down by channel, keeping the same Petavue session and definition, and returning a table of August and September pipeline and deals by channel
The follow-up stays in the same Petavue session, so it uses the same definition and date comparison

3. Ask where the answer came from

"Which sources did that answer come from?"

Every answer lists what Petavue referred to while answering: the workflows, tables, definitions, and context documents it read. It's a record of what was consulted. To see how a figure was actually calculated, ask how the number was built.

Codex listing the sources behind an answer in three groups: governed key definitions, live warehouse queries with the main table used, and verified workflow artifacts, followed by a note on confidence
Sources are grouped into key definitions, warehouse queries, and workflow artifacts

4. Ask how the number was built

"How did you get that number?"

Petavue explains the sources it consulted, the method it used, any data that was missing, and how confident it is in the figure.

Codex explaining how a 5 percent source-tag coverage figure was calculated from a live warehouse query, showing the deal counts checked and the division that produced the percentage
The explanation shows the query behind the number and the arithmetic that produced it

Other Things You Can Ask

Ask aboutFor example
Workflows"What Petavue workflows do I have access to?"
"What files did the weekly KPI workflow produce last run?"
Definitions"How does our workspace define qualified pipeline?"
Business context"Is there anything written down about our discount policy?"
Dashboards and files"Show me that dashboard."
"Download that CSV."
"Make a chart from that CSV."

Definitions and business context come from your workspace's context library. See Managing Context and Key Definitions. For more on workflows, see Understanding Workflows.

Getting Help

If you have questions, run into issues, or want to share feedback on the experience, reach out to us directly at support@petavue.com. We're available and responsive, and your input matters.

Petavue · What's New · September 22, 2026

On this page