Set up PipeLedger for AI agents

Start in the chat app you already use. Move to an agent on your own computer when you want it to know your business before you ask.

A chat app connects through a custom connector to https://mcp.pipeledger.ai/mcp. There are two routes, and an Owner or Admin chooses by who the person is.

Both routes apply the same access rules and leave the same audit record. The difference is what a person can see beyond their own answers. A member can open the PipeLedger application. A person with an access credential sees only answers about their slice.

Issue one access credential for each person. Disabling it ends every connection made with it. The steps and the token lifecycle are in the OAuth connection guide.

A working folder gives your agent a consistent reference for how your organization reports and reviews its finances. Keep your instructions, approved policies, and recurring procedures together so the agent can consult them during its work.

Start small: describe the business, explain what you need from reporting, and add one procedure you want help with. Expand the folder as you identify useful guidance.

What useful guidance looks like

You do not need a separate document for every topic. Use existing documents where they are current, and add short notes where important knowledge is still held by individuals.

The folder

your-organization/
  AGENTS.md                 organization context and working instructions
  reference/
    reporting-strategy.md
    chart-of-accounts.md
    accounting-policies.md
    intercompany-policy.md
  procedures/
    month-end-review.md
    variance-analysis.md
  notes/
    decisions.md
    open-questions.md
  reports/                  draft analyses and reviewed reports
  .pipeledger.json          connection selected for this folder

This is a suggested structure. Replace your-organization with your own folder and profile names throughout this page. Use the instruction filename supported by your agent, and link to the relevant reference documents and procedures from it. Codex reads AGENTS.md and Claude Code reads CLAUDE.md. Keep your existing document formats where practical.

The files guide the agent's work. Editing them does not change account mappings, metric definitions, or access permissions in PipeLedger.

Set it up

1. Install the agent and open it on the folder.
2. Write the instructions. The starter below is enough to begin with.
3. Add the guidance your finance team works from: your reporting strategy, chart-of-accounts structure, accounting policies, rules for keeping accounts and activities separate, intercompany policies, and review procedures. Start with the documents you already use and add context as questions arise.
4. Connect the books with the four commands below, then tell the agent to use the pl command.

npm install -g @pipeledger/cli
pl login
pl switch your-organization --here
pl whoami

pl login asks for the service credential with a hidden prompt and saves it outside the folder. An Owner or Admin creates that credential in PipeLedger and chooses its role, tools, data, and clearance. The command needs Node.js 20 or later.

Each saved credential is a profile: one organization, one name. Keep one folder for each organization and bind it once.

Each organization's folder selects its saved PipeLedger connection unless you explicitly override it. Open the agent in that folder and confirm the organization with pl whoami. File access is controlled by your agent's workspace permissions; the PipeLedger folder binding does not restrict which local files it can read.

YOURS: reused for every organization, holds none of their data
~/work/shared/
  procedures/
  templates/

ORGANIZATIONS: one folder each
~/work/organizations/
  organization-a/
    AGENTS.md
    reference/  procedures/  notes/  reports/
    .pipeledger.json   connection for organization A
  organization-b/
    AGENTS.md
    reference/  procedures/  notes/  reports/
    .pipeledger.json   connection for organization B

CREDENTIALS: private to you
~/.pipeledger/profiles/

Set up two organizations

Replace the folder and profile names with your own. Each pl login asks for that organization's service credential.

mkdir -p ~/work/organizations/organization-a
mkdir -p ~/work/organizations/organization-b

pl login --profile organization-a
cd ~/work/organizations/organization-a
pl switch organization-a --here
pl whoami

pl login --profile organization-b
cd ~/work/organizations/organization-b
pl switch organization-b --here
pl whoami

Each pl whoami should name the organization of the folder you are in, and show that the profile was chosen by the folder.

• One session, one organization. Start the agent inside the organization's folder. For another organization, start another session.
• Methods travel. Information does not. A procedure may be copied from your shared folder into an organization's folder. Nothing is copied from one organization to another.
• Bind folders for parallel work. Two agents in two bound folders can work on two organizations at the same time. A default that is switched back and forth is shared by every terminal, so it cannot do that.

What the folder binding does and does not do

• It selects a connection. .pipeledger.json names the profile and the organization. --profile on a command, or PIPELEDGER_PROFILE, overrides it for that command.
• It holds no credential. The folder can be synced or shared. A colleague who receives it must save their own credential for the same organization under the same profile name before the binding works on their computer.
• It does not limit file access. Your agent's workspace permissions decide which local files it can open, including another organization's folder.
• It is not authorization. PipeLedger enforces the credential's permissions on every request, whatever the folder says.

Several legal entities can share one connection and one folder when the credential's permissions cover them.

The profiles folder is the only place pl looks for saved profiles. A credential never belongs in an organization's folder, a chat message, an email, a screenshot, a typed command, or an agent's instructions.

How a profile is chosen

1. --profile <name> on the command, or PIPELEDGER_PROFILE.
2. The folder binding: the nearest .pipeledger.json in the current folder or a folder above it.
3. The default chosen with pl switch <name>.
4. The only saved profile, when exactly one is saved.

When nothing selects a profile, or the selection is missing or unreadable, the command returns a connection error. It never falls through to another organization. Before a financial request, pl also confirms with PipeLedger that the credential belongs to the organization the profile names.

The two automation settings are alternatives to a profile. Combining one with a profile or a bound folder is a conflict, and the command returns a connection error.

These are different acts. pl logout removes a credential from one computer. The credential still works anywhere else it was saved. Revoking it in PipeLedger ends it everywhere, and the next request is refused.

Sign out when you stop working for an organization or change computer. Ask an Owner or Admin to revoke when a credential may have been exposed or a person leaves. After signing out, pl does not choose another organization for you.

These rules apply when you act for a person who uses PipeLedger.

1. Run pl whoami before any other request, and state the organization you are working in.
2. Never ask a person to paste a credential into a conversation, and never write one into a file, a command, or your instructions. Ask them to run pl login themselves.
3. Do not open, copy, or move files in ~/.pipeledger/.
4. When a command returns a connection error, report the message. Do not work around it by setting an environment variable, naming another profile, or changing folder.
5. Work on one organization in one session. The folder binding does not stop you opening another organization's files, so do not open them, and do not carry figures, notes, or files from one organization's folder into another's.
6. If pl whoami reports a partial ledger, never present a result as the organization's complete ledger.
7. Return the evidence with the answer. The person reviews it, decides, and acts. PipeLedger does not post journals, send messages, or initiate payments.

If PipeLedger cannot safely select or authenticate a connection, the command returns an error instead of running the requested operation.

When you contact support, include the error code and any correlation ID shown. See the PipeLedger Tool Guide for what each command returns, and the support page for help.