Every expense-report and travel workflow Concur's web app offers, plus duplicate detection and real flight/hotel search no Concur tool has -- filed through the same session your browser already uses.
SAP Concur's official API requires enterprise partner credentials most individual users can never get. This CLI defaults to your logged-in browser session instead, so filing expense reports and checking travel works the same day you install it. Local SQLite sync turns your report history into something you can search, join, and validate offline.
Authentication
Concur's documented OAuth2 partner API is gated behind a Partner Enablement Manager relationship -- there is no self-serve signup, and this CLI does not implement that OAuth2 flow at all. Instead, this CLI authenticates via cookie/browser-session auth: run 'auth login --chrome', log into your company's Concur portal like you normally would (including SSO/MFA), and the CLI captures the resulting session. If a command fails with 401/403 and your company IT has partner OAuth2 credentials, that workflow requires calling the documented v3/v4 REST API directly (developer.concur.com) outside this CLI -- it is not something 'auth login' or any other command here can switch to.
Capturing the session with press-auth
press-auth opens its own Chrome window for a one-time login, so your daily Chrome needs no debug flags. Key the capture on your regional web host, not the apex: Concur scopes the _csrf cookie host-only to that host (for example us2.concursolutions.com), and press-auth drops host-only subdomain cookies from an apex-keyed capture.
press-auth login us2.concursolutions.com --login-url https://www.concursolutions.com
concur-pp-cli auth login --chrome
Open Expense once in the capture window so _csrf exists before the window closes. auth login reads the apex and every captured subdomain, newest capture first, and takes JWT and _csrf from a single capture rather than blending several. If it reports that the press-auth mise shim has no version, reinstall press-auth with the Go toolchain you use now: go install github.com/mvanhorn/cli-printing-press/v4/cmd/press-auth@latest.
auth login also refuses a capture whose JWT has already expired (a Concur token lasts about an hour) and leaves your stored session untouched; sign in again in the browser you capture from and re-run it.
hotels search has a second, separate login by default
hotels search drives its own agent-browser-controlled Chrome instance (see HTTP Transport below), which does not share cookies with auth login --chrome's source browser or credential store. Confirmed live that bridging them by copying cookies does not work -- Concur's bot-mitigation appears to bind the session to the browser/device that created it, not just the cookie value, so a copied JWT gets cleared by the server on the next navigation even when every cookie (including the Akamai bot-sensor ones) is copied alongside it. The first time (or whenever that session expires), hotels search opens its own Chrome window and asks you to log in there directly -- that login persists across later invocations until it expires again, so this is an occasional cost, not a per-search one.
Optional one-time setup to avoid that second login entirely (it applies to every browser-fallback command, not just hotels search): attach to a Chrome you have already logged into Concur with. Two ways to get one:
- A dedicated debug Chrome. Chrome 136 and later ignore
--remote-debugging-port unless a non-default --user-data-dir is also given, so use a dedicated directory and log into Concur there once:
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
--remote-debugging-port=9222 --user-data-dir="$HOME/.local/share/concur-pp-cli/chrome-debug"
- Your normal Chrome, through
chrome://inspect/#remote-debugging ("Allow remote debugging for this browser instance"). In that mode Chrome serves no HTTP discovery endpoints, so the CLI reads the WebSocket endpoint from Chrome's DevToolsActivePort file (in the user-data directory or in a profile directory under it; set CONCUR_CHROME_USER_DATA_DIR if yours is not in the default location).
Either way, keep a Concur page as that browser's active tab.
hotels search auto-detects that session (reads Chrome's DevToolsActivePort file, then tries CDP ports 9222, 9333, 9229 in order; set CONCUR_CDP_PORT to a port or a ws://127.0.0.1:... URL for a custom target) and attaches to it -- rather than copying its credentials -- before falling back to its own isolated login. Attaching, not copying, is what makes this work: it is the same live browser connection, so there is no separate device fingerprint for Concur's bot-mitigation to reject. Keep that Chrome window running whenever you plan to use hotels search; if you see "the dedicated Concur browser ... is no longer logged in", log in there again.
Browser-automation fallback for report creation
On Concur tenants where custom policies are required, creating a report via pure HTTP can fail with policyId is required because the request needs a policy ID. reports create first retries over the same authenticated HTTP session using the policy of your most recent report (it prints which policy it used; pass policyId in a --stdin body to choose another). Only if no policy can be inferred -- for example, you have no reports yet -- does it use a transparent browser-automation fallback: the command will automatically spin up agent-browser (using the same Remote Debugging CDP attach or isolated login as described for hotels search above), drive the report creation modal, and seamlessly fetch the resulting report details to return to you in the standard CLI format. This fallback is completely automatic and conditional; tenants that do not require policy ID selection will continue to use the fast, dependency-free HTTP API path.
The fallback derives which Concur web UI host to open from your configured API base URL, but only when that URL is actually a concursolutions.com host -- it will never silently guess a region. If you're on a supported proxy or custom endpoint where that derivation can't work, set CONCUR_UI_BASE_URL to the correct region's UI host explicitly (e.g. https://us2.concursolutions.com); without a derivable host or this override, the command fails with a clear error rather than risking the wrong tenant/region. If the click succeeds in Concur but a later step fails, the error will say so explicitly (with the report ID, when known) instead of looking like an ordinary, safely-retryable failure -- re-running reports create blindly at that point risks creating a duplicate report, so check reports get <id> or reports list first.
Browser-automation fallback for expense creation
Confirmed live: once an expenses create request body passes every client-side validation check, the API returns a generic HTTP 404 ("No static resource") instead of 201 -- this looks like a genuine Concur-backend defect, not a client-side bug, since deliberately-invalid bodies correctly get a clean 400 instead. expenses create has the same kind of transparent browser-automation fallback as reports create: on that exact 404 signature, it drives Concur's real "New Expense" form (same agent-browser CDP-attach-or-isolated-login mechanism as hotels search and the reports create fallback above) instead of failing outright.
Because the browser never surfaces a usable expense ID, success is confirmed by diffing the report's expense list before and after the form's Save click, correlated against the amount and expense type this call actually submitted (not just "any single new ID") -- a shared report modified concurrently through manager/processor/proxy contexts could otherwise have another actor's unrelated new expense misattributed as this call's own. Transaction Date is filled via Concur's calendar picker (day buttons carry a fully descriptive accessible name; text entry into the field itself does not reliably replace an existing value) rather than typed directly, so --date honors any date -- past, present, or future -- not just today. Payment Type's only verified-live value remains its own default (Cash) -- rather than silently substitute Cash for a --payment-type this can't honor and report success anyway, that one is still rejected up front, before the browser even opens. Vendor Description and Business Purpose are filled if requested; if either field can't be found or filled, the fallback aborts before the irreversible Save click instead of saving without a value the caller explicitly asked for. Like the reports create fallback, a failure after Save actually fires is reported as a possible partial success, not an ordinary retryable error. Triggers for a --stdin body just as reliably as the flag-driven path -- the fields it needs are read from the already-constructed request body, not the command's flag variables (which are always empty for a --stdin call).
Browser-automation fallback for expense update and report submission
Two sibling mutation endpoints hit their own live backend defects, fixed with the same pattern: expenses update (PATCH .../expenses/{id}, for --purpose and a --amount flag added specifically to support this) hits the identical 404 "No static resource" signature as expense creation's pre-fallback defect; reports submit (POST .../reports/{id}/submit) hits a different-shaped but same-root-cause defect -- every HTTP verb (POST, PUT, PATCH, DELETE) was tested against it live, and none reach the action server-side (POST/PUT/DELETE 405, PATCH 404).
expenses update's fallback opens the expense's direct edit URL, fills whichever of --purpose/--amount was requested, and verifies the re-fetched expense's fields actually match what was requested before reporting success -- a save that silently didn't register (the click fired but nothing changed) is reported as a failure, not trusted just because the follow-up GET itself succeeded. Business Purpose is a required field on Concur's form, so --purpose "" (requesting a clear) is rejected up front rather than opened in the browser to fail there. --comment/--custom-fields are accepted by the direct API path but not yet verified live through this fallback, so they're rejected the same way --date/--payment-type were for expense creation, above.
reports submit's fallback clicks the report page's "Submit Report" button, then the confirm button of the dialog that opens -- "Proceed" in the current "Report Summary" dialog, or a second, separate "Submit Report" button in the older "Report Totals" dialog (identically named to the page button while that dialog is open, so the fallback excludes the ref it already clicked rather than risking a re-click of the wrong one). Submission is confirmed via the re-fetched report's isSubmitted/approvalStatus fields before reporting success, for the same reason expense update's fallback re-verifies its own save.
Both fallbacks share expense creation's partial-success reporting: once either fallback's own irreversible confirm/save click fires, any later failure is reported as a possible partial success (not an ordinary retryable error), so re-running the command blindly doesn't risk a duplicate submission or an overwritten concurrent edit.
Quick Start
# Verify the binary and config are healthy before touching auth.
concur-pp-cli doctor --dry-run
# Capture your Concur session the same way you'd log in normally -- no API key needed.
concur-pp-cli auth login --chrome
# Get your Concur user ID once -- most commands need it via --user-id on every invocation (there's no built-in default-flag mechanism for it yet; export it as a shell variable to avoid retyping, e.g. USER_ID=$(concur-pp-cli account whoami --agent --select id --quiet)).
concur-pp-cli account whoami --agent
# See your existing expense reports.
concur-pp-cli reports list --user-id 550e8400-e29b-41d4-a716-446655440000 --agent
# Create a report the same way the web UI's 'Create Expense Report' button does.
concur-pp-cli reports create --name "October Travel" --purpose "Client site visit" --user-id 550e8400-e29b-41d4-a716-446655440000
Unique Features
These capabilities aren't available in any other tool for this API.
Conditional browser fallback for report/expense creation, expense update, and report submission
reports create — Retries report creation over HTTP with the policy of your most recent report when the Concur v4 API rejects the request with a policyId is required error, and falls back to an automated browser only when no policy can be inferred. Both paths are conditional and only trigger for tenants requiring explicit policy assignment.
expenses create — Automatically and transparently retries expense creation via automated browser when the API returns its confirmed-live 404 defect on an otherwise fully-valid request. Success is confirmed by diffing the report's expense list rather than trusting a browser-surfaced ID, since the browser gives none. Any --date, not just today, is honored via Concur's calendar picker.
expenses update — Same 404 defect as expense creation, on the sibling PATCH path. Fills --purpose/--amount and verifies the re-fetched expense's fields actually changed before reporting success.
reports submit — A different-shaped (405, not 404) but same-root-cause defect: no HTTP verb reaches the submit action server-side. Clicks through Concur's confirmation dialog ("Proceed" in the current "Report Summary" dialog, or a second "Submit Report" button in the older "Report Totals" dialog) and confirms isSubmitted before reporting success.
receipts — POST /receiptimages/v1/{expense_id} returns HTTP 404 on this tenant, so the command tries it first and, on a 404, falls back to the expense's edit page when --report-id (and --user-id) are given: it uploads the file through the page's file input (the receipt attaches immediately; no Save click is needed) and confirms the expense's receiptImageId is populated before reporting success. It refuses to attach a second receipt to an expense that already has one. Accepted types: png, jpg, jpeg, pdf, tif, tiff, up to 20 MB.
The fallbacks drive a real Chrome page. If that window is hidden or minimized, Chrome reports the page as not visible and Concur's date picker will not open, so the fallbacks first activate the tab and stop with an actionable error if the page stays hidden. Slow page loads no longer abort a fallback when the target page did load, and an expenses create/expenses update save click that errors but actually saved is verified against the report before the command reports a result.
Itemization lines: inspect and fix
-
expenses itemizations — Lists an expense's itemization lines (its child expenses, each carrying parentExpenseId), which expenses list and expenses get do not include.
Use this to see how an itemization-required expense, such as a hotel folio, is split and which lines still have the placeholder Undefined type.
concur-pp-cli expenses itemizations <expense_id> --report-id <report_id> --user-id <uid> --agent
-
reports exceptions — Lists a report's validation exceptions and which of them block submission. The per-expense hasExceptions flags can read false while blocking exceptions exist, so this is the authoritative check before reports submit.
concur-pp-cli reports exceptions <report_id> --user-id <uid> --agent
-
expenses update --type — Changes an itemization line's expense type through the browser, because the API rejects expense writes for browser-session auth (a no-op PATCH returns the same 404 on both host families). Opens the line's form, picks the named type from the policy-filtered picker, saves, then re-fetches the line and verifies the type took and the amount did not move. If the requested type is not offered it stops without saving and lists the types that are. Itemization lines only.
concur-pp-cli expenses update <itemization_expense_id> --report-id <report_id> --user-id <uid> --type "Hotel" --agent
Local state that compounds
-
expenses scan-duplicates — Find potential double-entered charges across all of your synced expenses. Run concur-pp-cli sync --resources expenses --user-id <uid> first: it fetches each recent report's expenses (newest 100 reports by default; --max-pages to widen) into the local store, and the scan refuses to run on a never-synced store and reports how old the synced data is. Each sync also drops local rows for expenses that were removed from a report you re-fetched (--no-prune keeps them); expenses of a report you deleted outright stay until the local store is cleared.
Run this before submitting a batch of reports if you suspect a corporate-card charge and a manually-entered cash expense might be the same transaction.
concur-pp-cli expenses scan-duplicates --agent
Live travel shopping (search only, never books)
-
flights search — Real flight availability and fares from a live shopping session against your actual corporate-negotiated rates and travel policy -- not a public fare aggregator. One-way by default; --return includes both legs in the search but only renders the outbound leg (see --help for the known gap).
Use this to compare real options before requesting travel, with policy-compliance flags already applied per fare.
concur-pp-cli flights search --from LAX --to "New York" --depart 2026-10-12 --yes --agent
-
hotels search — Real hotel availability and rates via a live, policy-scoped search -- the same inventory and pricing Concur's own Hotel Search page shows. Drives a real browser (see HTTP Transport and Authentication below) rather than a direct API call, because the hotel shopping-session mutation is blocked from scripted replay by the tenant's bot-mitigation.
A one-time dedicated-browser setup (see Authentication) avoids a separate login every time this command's session expires.
concur-pp-cli hotels search --to "New York" --check-in 2026-10-12 --check-out 2026-10-18 --yes --agent
Recipes
Check for duplicate charges
concur-pp-cli sync --resources expenses --user-id <uid> --agent
concur-pp-cli expenses scan-duplicates --agent
Attach a receipt to an expense
concur-pp-cli receipts <expense_id> --file receipt.pdf --report-id <report_id> --user-id <uid> --agent
concur-pp-cli expenses list --user-id <uid> --report-id <report_id> --no-cache --agent # receiptImageId should now be set
Scan the local SQLite cache for likely double-entered transactions across all your reports.
See what's actually on an existing report
concur-pp-cli expenses list --user-id <uid> --report-id <report_id> --agent
reports get returns only the report header (name, total, status, dates) -- this is the only
live way to see the report's actual line items: each expense's ID, type, vendor, business
purpose, amount, and receiptImageId (the field to check, non-null, to confirm a receipt
attachment actually persisted server-side rather than trusting a mutating call's own reported
success).
Find what blocks a report from submitting, and fix itemization types
concur-pp-cli reports exceptions <report_id> --user-id <uid> --agent
concur-pp-cli expenses itemizations <expense_id> --report-id <report_id> --user-id <uid> --agent
concur-pp-cli expenses update <itemization_expense_id> --report-id <report_id> --user-id <uid> --type "Hotel" --agent
reports exceptions is the authoritative list of what blocks submission (isBlocking: true); the
per-expense hasExceptions flags in expense payloads can read false while exceptions exist. An
UNDEFEXP exception means an itemization line still has the placeholder Undefined type.
expenses itemizations shows the lines (and their expenseIds) of an expense that requires
itemization, such as a hotel folio. expenses update --type takes the type's name as shown in
Concur's picker and works on itemization lines only. The picker is policy-filtered: a type can
appear in expense-types list yet not be selectable, in which case the command stops without
saving and lists the types that are offered. It drives the browser (see the setup note below).
Over MCP these are the reports_exceptions, expenses_itemizations and expenses_update_type tools.
Compare real flight and hotel options before requesting travel
concur-pp-cli flights search --from LAX --to "New York" --depart 2026-10-12 --yes --agent
concur-pp-cli hotels search --to "New York" --check-in 2026-10-12 --check-out 2026-10-18 --yes --agent
Both create a live shopping session against your real tenant -- searches only, never books. flights search is a direct API call; hotels search drives a real browser (see HTTP Transport and Authentication) and is markedly slower.
File a manual expense line item (e.g. a recurring personal-reimbursement stipend)
concur-pp-cli expenses create \
--report-id <report-id> --user-id <user-id> \
--type 01000 --date 2026-09-15 --amount 50 \
--payment-type CASH --vendor "F45 Training Culver City" --business-purpose "gym" \
--agent
--type/--payment-type take the expenseTypeId/paymentTypeId codes from expense-types list/payment-types (not display names). --vendor and --business-purpose are distinct
Concur form fields (confirmed live 2026-09-15) -- "Vendor Description" is who you paid,
"Business Purpose" is why; don't conflate them (e.g. don't put "gym" in --vendor, it belongs
in --business-purpose). Setting --business-purpose at creation time also means you never need
expenses apply-rules' PATCH-based fill, which hits this same command's confirmed-live 404
defect just like creation itself used to. --currency set to anything other than USD is
rejected -- no working currency-override field has been confirmed live for this endpoint, and
silently creating an expense in the report/policy default currency instead of what was requested
is a correctness bug, not an acceptable fallback; omit --currency (or pass USD) and correct
the currency manually in Concur afterward if you truly need a different one. If the API's
confirmed-live 404 defect fires on this request, it now falls back to browser automation
automatically instead of just failing -- see "Browser-automation fallback for expense creation"
under Authentication. That fallback honors any --date via Concur's calendar picker, but will
still reject rather than silently substitute a default for a non-Cash --payment-type it can't
reliably honor.
Usage
Run concur-pp-cli --help for the full command reference and flag list.
Paths & environment variables
This CLI separates local files into four path kinds:
| Kind | Contents |
|---|
config | User-editable settings such as config.toml and saved profiles |
data | Durable local data: credentials.toml, data.db, cookies, browser-session proof files, and other auth sidecars |
state | Runtime state such as persisted queries, jobs, and teach.log |
cache | Regenerable HTTP/cache files |
Each kind resolves independently. The ladder is:
- Per-kind env var:
CONCUR_CONFIG_DIR, CONCUR_DATA_DIR, CONCUR_STATE_DIR, or CONCUR_CACHE_DIR
--home <dir> for this invocation
CONCUR_HOME for a flat relocated root
- XDG env vars:
XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME
- Platform defaults matching existing installs
For containers and agent sandboxes, prefer a single relocated root:
export CONCUR_HOME=/srv/concur
concur-pp-cli doctor
Under CONCUR_HOME=/srv/concur, the four dirs resolve to /srv/concur/config, /srv/concur/data, /srv/concur/state, and /srv/concur/cache.
MCP servers do not receive CLI flags from the host. Put relocation in the host env block:
{
"mcpServers": {
"concur": {
"command": "concur-pp-mcp",
"env": {
"CONCUR_HOME": "/srv/concur"
}
}
}
}
Precedence matters in fleets: an ambient per-kind variable such as CONCUR_DATA_DIR overrides an explicit --home for that kind. Use CONCUR_HOME or the per-kind variables for durable fleet relocation; treat --home as the weaker per-invocation lever.
Relocation is one-way. Unsetting CONCUR_HOME does not move files back to platform defaults, and doctor cannot find credentials left under a former root. Move the files manually before unsetting relocation variables.
Existing installs keep working because the platform-default rung matches the legacy layout. On the first auth write, stored secrets leave config.toml and are consolidated into credentials.toml under the data directory. Run concur-pp-cli doctor --fail-on warn to check path and credential-location warnings in automation.
Commands
account
Current user profile, policies, and delegate context
concur-pp-cli account travel <user_id> - Get the current user's travel profile and loyalty programs
concur-pp-cli account whoami - Get the current user's profile, addresses, and travel IDs
attendees
Attendee catalog and per-expense attendee associations
concur-pp-cli attendees add - Add attendees to an expense (merge-preserves existing associations; Concur's underlying association call is a replace, so this reads first then re-POSTs the union)
concur-pp-cli attendees list - Get attendees currently associated with an expense
delegates
Delegate (act-on-behalf-of) relationships
concur-pp-cli delegates - List users the current session user delegates for, with permission flags
expense_types
Expense type catalog and per-type dynamic form fields
concur-pp-cli expense-types list - List usable expense types for the current user's policy
expenses
Expense line items within a report
concur-pp-cli expenses create - Create an expense inside a report (core v3-equivalent fields: type, date, amount, currency, payment type)
concur-pp-cli expenses get - Get a single expense with its filled/empty field manifest
concur-pp-cli expenses list - List every expense line item on a report (the only live way to enumerate an existing report's expenses -- reports get returns only the header)
concur-pp-cli expenses itemizations - List the itemization lines of an expense (child expenses; expenses list and get do not include them)
concur-pp-cli expenses update - Fill or change writable fields on an expense (core + custom/list fields)
flights
Search flight locations, travel policy preferences, and real flight availability (creates a live shopping session -- searches only, never books)
concur-pp-cli flights locations <query> - Resolve an airport, city, or metro name to Concur's travel location IDs; metro queries (e.g. "New York") resolve to one search endpoint covering all constituent airports
concur-pp-cli flights preferences - Show your travel policy's flight search defaults
concur-pp-cli flights search --from <origin> --to <dest> --depart <date> [--return <date>] - Search real flight availability and fares
hotels
Search real hotel availability and rates (drives a real browser search -- searches only, never books)
concur-pp-cli hotels search --to <destination> --check-in <date> --check-out <date> - Search real hotel availability and rates; requires agent-browser installed (see HTTP Transport and Authentication below)
lists
Valid values for list-type expense form fields
concur-pp-cli lists --list-id <id> - Get valid values for a list-type form field by list ID
locations
Location catalog for filling expense/attendee location fields
concur-pp-cli locations <query> - Search the location catalog by city or venue name
payment_types
Payment type catalog (Cash, Company Card, etc.)
concur-pp-cli payment-types - List payment types available to the current user
receipts
Receipt image/PDF attachment
concur-pp-cli receipts <expense_id> --file <path> - Attach a receipt image or PDF to an expense (on an HTTP 404, pass --report-id/--user-id to attach through the browser)
reports
Expense report headers and lifecycle
concur-pp-cli reports create - Create a new expense report header
concur-pp-cli reports exceptions - List a report's validation exceptions (what blocks submit)
concur-pp-cli reports get - Get a report's header
concur-pp-cli reports list - List the current user's expense reports
concur-pp-cli reports submit - Submit a report for approval
concur-pp-cli reports update - Update a report's name or business purpose
requests
Travel requests / pre-trip authorization (UNVERIFIED paths -- see spec header notes)
concur-pp-cli requests get - Get a travel request's detail and workflow status
concur-pp-cli requests list - List the current user's travel requests
travel_allowance
Per-diem / travel allowance calculations (UNVERIFIED path -- see spec header notes)
concur-pp-cli travel-allowance <trip_id> - Get travel allowance (per-diem) calculation results for a trip
trips
Booked trips and itineraries (UNVERIFIED paths -- see spec header notes)
concur-pp-cli trips get - Get a trip's itinerary detail
concur-pp-cli trips list - List the current user's upcoming and past trips
Self-learning loop
This CLI caches per-question discovery so repeat queries skip the walk and structurally similar queries get answered via entity substitution. The loop also self-captures: every invocation is journaled locally, and failed-flag corrections plus fresh teaches surface as candidates on the next recall for confirm/reject judgment. Agents call recall before discovery and fire teach & after answering. See the ## Automatic learning section in SKILL.md for the full protocol.
concur-pp-cli recall <query> - Look up cached resources for a query before running discovery
concur-pp-cli teach - Record a query -> resource mapping (silent on success, safe to background with &)
concur-pp-cli learnings list - Inspect taught rows
concur-pp-cli learnings forget <query> - Undo a teach
concur-pp-cli learnings candidates - List auto-captured candidates awaiting confirm/reject
concur-pp-cli learnings stats - Local loop metrics: recall hit rate, teach-to-reuse, playbook resolution, candidate counts
concur-pp-cli teach-pattern - Install a query/resource template up front
concur-pp-cli teach-lookup - Add an entity mapping (e.g. country code, team alias) for pattern substitution
Pass --no-learn or set CONCUR_NO_LEARN=true to disable the loop for deterministic flows.
The local store's schema version stamp is one-way: once this version of concur-pp-cli opens the database, older binaries refuse it with a version error — upgrade the binary rather than downgrading.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
concur-pp-cli payment-types
# JSON for scripting and agents
concur-pp-cli payment-types --json
# Filter to specific fields
concur-pp-cli payment-types --json --select paymentTypeId,paymentTypeName,description
# Dry run — show the request without sending
concur-pp-cli payment-types --dry-run
# Agent mode — JSON + compact + no prompts in one flag
concur-pp-cli payment-types --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select <field>[,<field>...] returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
concur-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Run concur-pp-cli doctor to see the resolved config, data, state, and cache directories. The platform-default config path is ~/.config/concur-pp-cli/config.toml; --home, CONCUR_HOME, and per-kind env vars can relocate it.
Static request headers can be configured under headers; per-command header overrides take precedence.
Troubleshooting
Authentication errors (exit code 4)
- Run
concur-pp-cli doctor to check credentials
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- auth login --chrome captures no cookies or the session expires quickly — Install press-auth (go install github.com/mvanhorn/cli-printing-press/v4/cmd/press-auth@latest) for a more reliable capture: press-auth login concursolutions.com --login-url https://www.concursolutions.com/ --jwt-carrier-cookie JWT
- reports submit fails with 'Missing required field: Business Purpose' — Auto-fill known-rule expense types via 'concur-pp-cli expenses apply-rules --user-id --config expense_types.json'; run it with --dry-run first to preview the changes without writing anything.
- every command wants --user-id and I don't want to retype my own GUID constantly — This CLI has no built-in default-flag mechanism for --user-id yet ('profile save' only captures global output flags like --json, not per-command flags). Export it as a shell variable instead. First capture your ID:
USER_ID=$(concur-pp-cli account whoami --agent --select id --quiet). Then pass it on other commands: --user-id "$USER_ID".
- commands fail with 401/403 against reports or expenses endpoints — Your company's Concur tenant may route those calls through the OAuth2 partner API instead of the cookie-authenticated path this CLI uses by default. This CLI does not implement the OAuth2 partner flow; if your company IT has partner credentials, use the documented v3/v4 REST API directly (developer.concur.com) for that workflow instead.
hotels search keeps opening its own Chrome window and asking me to log in, separately from auth login --chrome — Expected: it drives a different, isolated browser instance and cannot share credentials with auth login --chrome's source browser (copying cookies between them was tried and confirmed not to work -- see Authentication above). The login persists across later invocations until that session expires, so this is occasional, not per-search. To avoid it entirely, set up a dedicated debug-enabled Chrome profile once (see Authentication above); hotels search auto-detects and attaches to it instead of opening its own.
expenses create fails with HTTP 404 "No static resource .../expenses" even though the request looks correct — Confirmed live across ~15 real-request trials: this happens specifically once a request body passes every field-type check (i.e. it is otherwise well-formed) -- deliberately-invalid bodies get a clean HTTP 400 instead. This looks like a genuine Concur-backend defect (or a tenant/policy-specific server issue), not a client-side body-shape bug. As of this version, expenses create falls back to browser automation on this exact signature automatically (see "Browser-automation fallback for expense creation" under Authentication) -- if you're seeing the raw 404 instead of a fallback attempt, check that agent-browser is installed (npm install -g agent-browser && agent-browser install). If the fallback itself fails partway through, the error says so explicitly and will not look like an ordinary retryable failure -- check the Concur web UI for the report in question before retrying by hand, to avoid a duplicate line item.
expenses create rejects --currency (non-USD), or the browser fallback rejects a non-Cash --payment-type — Expected, not a bug: neither can be reliably honored on this endpoint/form as currently confirmed live (see the rows above and "Browser-automation fallback for expense creation" under Authentication). Earlier versions silently substituted a default (USD, Cash) and still reported success, which is a worse failure mode than a loud rejection -- creating an expense with data the caller didn't ask for. Omit the flag to accept the default explicitly, or correct the field manually in Concur after creation. (--date is NOT in this category -- any date is honored via Concur's calendar picker.)
expenses update --purpose "" is rejected — Expected: Business Purpose is a required field on Concur's expense-edit form, so clearing it isn't honorable through this fallback. Set a non-empty --purpose, or clear it manually in Concur if your policy genuinely allows an empty value.
HTTP Transport
This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls.
Exception: hotels search. Confirmed live that Concur's hotel shopping-session mutation is blocked from scripted HTTP replay by the tenant's bot-mitigation (byte-for-byte replay of a request that had just succeeded natively in the browser still failed). So this one command drives a real browser via agent-browser instead (npm install -g agent-browser && agent-browser install) -- flights search and every other command remain pure HTTP; only the hotel-shopping mutation needs a real browser.
TLS certificates are verified by default. For a trusted development or self-signed endpoint only, pass --insecure for one invocation, set CONCUR_SKIP_TLS_VERIFY=true for the current environment, or set skip_tls_verify = true in the config file for a persistent override.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press