pierre is the command-line tool for Code Storage. Each API command calls
one operation of the HTTP API through @pierre/sdk, with the same name and the same fields as the
SDK method. The helpers store a private key and make plain Git work against every Code Storage
repository.
Docs for agents
Read the docs through the MCP server first, then as Markdown pages:
Each operation has a catalog ID, for example repos.branches.create. Search for the catalog ID in
the docs. prints the MCP server and the command that installs the agent skill.
npm install -g @pierre/clipierre versionnpx @pierre/cli version
The CLI needs Node.js 22.23.4 or a later 22 release, 24.22.1 or a later 24 release, or 26.12.1 or
later. Run pierre auth setup-git from a global install: Git stores the path of that pierre, and
npx and pnpm dlx run the CLI from a cache that can change.
Quick start
Create a key on the Keys page of your organization dashboard, and keep the private key in your
secrets manager. Then store it, and let Git get its credential from pierre:
pierre auth login --hostname acme.code.storage --with-key < key.pempierre auth setup-git
Create a repository, and push a local repository to it:
pierre repos create my-appgit remote add storage https://acme.code.storage/my-app.gitgit push -u storage main
git clone https://acme.code.storage/my-app.git, git fetch, and git push now work. Git URLs
contain no credential.
CI and containers
Configure Git when you build the image. Put no secret in the image.
pierre auth setup-git --hostname acme.code.storage
At runtime, set PIERRE_PRIVATE_KEY to the private key PEM, so that no key touches the disk. The
other variables depend on the command and the host:
Git on an <org>.code.storage host needs no other variable. The helper takes the organization
from the host that Git sends.
An API command takes the organization from an <org>.code.storage remote of the current clone.
Outside such a clone, also set PIERRE_ORG.
A host on another domain needs PIERRE_ORG for Git, and also PIERRE_GIT_HOST and
PIERRE_API_BASE_URL for an API command.
A job with no private key can set PIERRE_TOKEN to a token that another system signed. The CLI and
the Git helper send that token and sign nothing. The claims of the token limit what the job can do.
A job with no hosts file sets the organization and, for a host outside <org>.code.storage, the
hosts, as for the SDKs:
export PIERRE_ORG=acmeexport PIERRE_PRIVATE_KEY="$(cat key.pem)"export PIERRE_GIT_HOST=git.example.comexport PIERRE_API_BASE_URL=https://api.example.compierre repos list --json
API commands
The command is the catalog ID with : between the resources, then the method. The flags are the
fields of the SDK method, with the wire names in kebab-case:
Catalog ID
SDK method
Command
repos.list
pierre.repos.list()
pierre repos list
repos.get
pierre.repos.get()
pierre repos get acme/web
repos.branches.create
pierre.repos.branches.create()
pierre repos:branches create --repo-name acme/web --target-branch feat --base-ref main
pierre --help lists every API command, and pierre <resource> <method> --help gives its flags,
its catalog ID, its HTTP route, and its scopes.
Singular nouns.pierre repo list and pierre repo:branch create run the plural commands.
pierre repo view runs pierre repos get.
One argument. A command takes at most one positional argument: the resource it acts on. Its
flag works too: pierre repos:branches create feat equals
pierre repos:branches create --target-branch feat.
The repository.-R is the short form of --repo-name. Inside a clone with a Code Storage
remote, --repo-name defaults to that repository, except for repos delete:
pierre repos:branches create feat -R acme/web --base-ref maincd web && pierre repos:branches create feat --base-ref main
Flag values. A boolean is --force or --no-force. An array takes its flag once for each
item. An object takes JSON, @file, or @- for stdin, and each of its scalar fields also has a
dotted flag: --author.name A --author.email a@example.com.
Content.pierre repos:commits create takes --file <path> for each file to add or change,
read from the same path under the current directory, and --delete <path> for each file to
delete. pierre repos:commits create-from-diff takes --diff <file>, or --diff - for stdin.
Output.--json prints the response body. Without it, an object prints one row for each
field, and a list prints a table. A list prints one page: --limit and --cursor are the wire
fields, and --paginate reads every page. A byte response, such as pierre repos:files get,
writes to stdout or to --output <file>.
Status. When an operation can answer with more than one success status, the output starts with
the status. pierre repos create prints 201 Created for a new repository, and 200 OK for an
existing one.
Confirmation.pierre repos delete asks first. Pass --yes with no terminal.
pierre api
pierre api <catalog-id> calls any operation through its SDK method, and prints the JSON response
body. As in gh api, path parameters are fields:
pierre api repos.branches.create -F repo_name=acme/web -F target_branch=feat -F base_ref=main
-F key=value sends a typed value: true, false, null, an integer, @file, @-, or text.
-F key[name]=value sets a field of an object. -F key[]=value adds an item to an array, and so
does -F key=value for an array field. Give the flag once for each item.
-f key=value sends a string.
--input <file> (- for stdin) gives the body fields as one JSON object. Then -F and -f set
only path, query, and header fields.
A field that the operation does not have is a usage error.
Helpers
pierre auth login [--hostname <host>] [--org <org>] [--api-url <url>] [--from-file <path>] [--no-verify] --with-keypierre auth status [--hostname <host>] [--json]pierre auth logout [--hostname <host>] [--yes]pierre auth token [--repo <repo>] [--scope <scope>]... [--ttl <duration>] [--hostname <host>]pierre auth setup-git [--hostname <host>] [--local] [--read-only] [--uninstall]pierre auth git-credential <get|store|erase> # called by Gitpierre api <catalog-id> [-F key=value]... [-f key=value]... [--input <file>]pierre mcp [--json]pierre version [--json]
pierre auth login checks the key with repos.list, then stores it under
~/.config/pierre/keys/. It prints the host, the organization, the key file, and the key ID.
pierre auth status reports each host: the organization, the key source, the key ID, a live
check, and the Git helper settings.
pierre auth token prints a token from createToken of @pierre/sdk/auth. --scope takes a
scope of SCOPES from @pierre/sdk/auth, and defaults to git:read and git:write. An unknown
scope is a usage error that lists the scopes of SCOPES. A token whose scopes all cover the
organization (org:read) has no repo claim. Another token needs --repo, which defaults to the
Code Storage remote of the current repository. --ttl defaults to 15 minutes, up to 1 hour.
pierre auth setup-git configures Git to get its credential from pierre (see
Git credential helper).
pierre mcp prints the docs MCP server, the Markdown index, the auth note, and the skill command,
and the organization and API URL of the selected host when they resolve. It reads the MCP server
from https://code.storage/.well-known/mcp.json, with a 15-second timeout, and prints
https://code.storage/docs/mcp when that request fails. PIERRE_DASHBOARD_URL replaces
https://code.storage. --json prints a config block for an MCP client.
Global flags
Flag
Meaning
--debug
Print to stderr the repository taken from the Git remote, the token steps of the credential helper and of auth token, and the stack of an unexpected error. Never prints a token
-h, --help
Show help
--hostname <host>
Select a tenant by its Git host. Overrides PIERRE_GIT_HOST and the current repository's remote.
--json
Print the JSON response body
--no-input
Fail instead of prompt
--quiet
Print only results and errors
-v, --version
Print the CLI version
--yes
Skip confirmations
Exit codes
The exit code comes from the class of the SDK error, never from the message text.
Code
Meaning
0
Success
1
Another API error, such as a conflict or a 5xx, or no connection
2
Usage error
3
Credential problem: no key, a malformed key, 401, or 403
4
Not found: 404
An API error prints its status, its problem code, its detail, the request ID, and the docs of the
code. With --json, the CLI also prints the problem details body on stdout.
Configuration
Configuration lives in ~/.config/pierre/. When XDG_CONFIG_HOME is set, that directory replaces
~/.config. PIERRE_CONFIG_DIR replaces the whole path.
The Git host. It selects the saved configuration and the Git credential helper.
git.example.com
--org
The organization that owns the key. The CLI puts this value in the token's iss claim.
acme
--api-url
The REST API endpoint for the API commands, such as repos list.
https://api.example.com
The hostname accepts an http:// or https:// prefix, but stores only the host. The API URL needs
a scheme because it sets the HTTP transport. The API URL accepts an origin or a base URL that ends
in /api/v1.
Several organizations can share one API URL. The server uses the signed token to identify the
organization. For example, acme.example.com and beta.example.com can both use
https://api.example.com, with separate organization names and keys. Get these values from the
service configuration; a custom Git hostname alone does not establish the organization or API URL.
Other clusters use a separate API URL for each tenant. Do not assume that an API URL which works for
one tenant also works for another.
Use pierre auth status --hostname <host> to inspect the saved organization and API URL. If you
repeat login for a custom host, pass --org and --api-url again.
Environment variables
Variable
Meaning
PIERRE_API_BASE_URL
The API base URL, for a host with no host entry. An origin or a URL that ends in /api/v1
PIERRE_CONFIG_DIR
Replaces ~/.config/pierre
PIERRE_DASHBOARD_URL
The origin of the agent discovery documents for mcp. Default https://code.storage
PIERRE_DEBUG
Helper diagnostics to stderr
PIERRE_GIT_HOST
The Git host when no --hostname is given. It selects the host entry of that host, or else uses the variables, as the SDKs do
PIERRE_ORG
The org, for an environment with no hosts table or a host outside the default shape
PIERRE_PRIVATE_KEY
The private key PEM itself, or the PEM on one line with a literal \n for each line break. Nothing is read from disk
PIERRE_PRIVATE_KEY_FILE
A path to the private key
PIERRE_TOKEN
A JWT to send on each call. The CLI signs no token and needs no private key. The token's claims set its access
PIERRE_TOKEN_TTL
Helper token lifetime in seconds, from 1 to 3600. Default 3600
Each token that the CLI signs has the key ID as its JWT kid header. The key ID is the hex SHA-256
of the public key, and pierre auth status shows it.
Resolution rules
First match wins.
Host, the Git host:
--hostname.
PIERRE_GIT_HOST.
A remote of the current repository: first a remote whose host has a host entry, then a remote
on an <org>.code.storage host. In each group, the remote named storage comes first. The CLI
does not use a remote on another host.
The only host entry, when hosts.yml has exactly one.
<org>.code.storage, when hosts.yml has no entry, for the org from PIERRE_ORG or the iss
claim of PIERRE_TOKEN.
With several host entries and none of the first three, the command exits 2 and lists the hosts. A
host with a host entry uses its org, its API URL, and its key file. Another host uses the
variables.
Credential: PIERRE_TOKEN, PIERRE_PRIVATE_KEY, PIERRE_PRIVATE_KEY_FILE, the host entry's
key file.
Org: the host entry, PIERRE_ORG, the iss claim of PIERRE_TOKEN, the subdomain of a
*.code.storage host.
API URL: the host entry, PIERRE_API_BASE_URL, https://api.<org>.code.storage/api/v1.
Git credential helper
Code Storage Git remotes use HTTP Basic authentication: the username is the literal t, and the
password is a JWT that your private key signs. pierre auth setup-git writes these Git settings
once per host:
The blank helper line stops Git from asking another helper, such as a keychain, for this host.
useHttpPath makes Git send the repository path, which the helper needs.
The helper command starts with an absolute path. setup-git selects it as follows:
When a pierre on PATH starts this CLI, the helper is the path of that pierre. It is a link
from npm install -g, npm link, or bun add -g, or the script that pnpm add -g writes, such
as ~/Library/pnpm/bin/pierre. The path stays the same when the CLI or Node.js changes version.
This command runs node from the PATH that Git uses.
Otherwise, the helper names the Node.js executable and the CLI script:
!<path of node> <path of dist/cli.js> auth git-credential. For example, npm install -g under
proto puts its link in a directory that is not on PATH. This command needs no PATH, but it
names one Node.js version and one CLI location. Run pierre auth setup-git again after a change
of either.
npx and pnpm dlx run the CLI from a cache that can change or expire. setup-git shows a warning
when the helper path is in one of these caches.
On each Git operation:
Git runs pierre auth git-credential get and writes the protocol, the host, and the path to its
stdin.
The helper takes the repository from the path: it strips .git, strips a +ephemeral or
+import suffix, and decodes each segment.
It resolves the org from the host and the credential by the
resolution rules. When PIERRE_TOKEN is set, it prints that token and skips
the next step.
It signs a token with git:read and git:write, or git:read only in read-only mode, that
lives for one hour by default. PIERRE_TOKEN_TTL sets another lifetime in seconds, up to one
hour.
It prints username=t and password=<token>. It stores nothing.
On any failure the helper prints quit=true, so Git never falls through to a password prompt, and
one line to stderr that names the cause.
store and erase do nothing, because nothing is persisted.
Remove the settings with pierre auth setup-git --uninstall.
Troubleshooting
Message
Cause
Fix
credential helper: Git sent no path
useHttpPath is not set for the host
Run pierre auth setup-git
credential helper: No private key is configured
No key file for the host and no PIERRE_PRIVATE_KEY
Run pierre auth login --hostname <host> --with-key
credential helper: Cannot derive the organization
The host is outside <org>.code.storage and has no host entry
Log in with --org and --api-url, or set PIERRE_ORG
The private key is on one line (exit 3)
The paste lost its newlines, from a text selection or a password field
Use the dashboard copy button, and store the key in a multi-line field
401 unauthorized or 403 insufficient_scope (exit 3)
The server rejected the token or its permissions
Read the server's error detail. Check the organization, key, and permissions, then use the retry command.
git push fails with 403
The machine is in read-only mode
Run pierre auth setup-git without --read-only
node: not found or env: node: No such file
Git has no node on its PATH, for example in an app from the Dock
Start the Git app from a shell, or put node on the PATH of the app
Cannot find module or <path>/node: No such file
The helper names a Node.js or CLI path that an update removed
Run pierre auth setup-git again
Rotate a key
Create a new key on the dashboard Keys page.
Store it for the same host. This replaces the key file and the host entry, so no logout is
needed:
pierre auth login --hostname acme.code.storage --with-key < new-key.pem
Confirm with pierre auth status. The key ID changes and the live check passes.
Delete the old key on the dashboard.
pierre auth logout deletes the selected host entry and its local key file. Use it when a machine
must stop using a key, then revoke the key on the dashboard.
License
Apache 2.0. See LICENSE. dist/cli.js bundles its dependencies, and
dist/THIRD_PARTY_LICENSES.txt gives the license of each bundled package.