Skip to content

README.md

Latest commit

 

History

History
92 lines (63 loc) · 3.38 KB

README.md

File metadata and controls

92 lines (63 loc) · 3.38 KB
Raw

pipefy-cli

Typer-based CLI for Pipefy. Exposes all MCP tool capabilities as terminal commands and scripts. Depends on pipefy-sdk for GraphQL calls.

Install (pre-launch, v0.1 → v0.5)

uvx \
  --with "pipefy-sdk @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/sdk" \
  --with "pipefy-auth @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/auth" \
  --from "git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/cli" \
  --refresh pipefy-cli

Or persistently:

uv tool install \
  --with "pipefy-sdk @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/sdk" \
  --with "pipefy-auth @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/auth" \
  "git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/cli"

The --with flags are required pre-1.0 because the workspace members are not yet on PyPI. At v1.0 this collapses to uv tool install pipefy-cli.

Quick start

# Show all commands
pipefy --help

# Card operations
pipefy card get 12345 --json
pipefy card list --pipe 67890
pipefy card create --pipe 67890 --title "New card"

Agent skills are installed separately via skills.sh; see skills/README.md.

Configuration

Same PIPEFY_* environment variables as pipefy-mcp-server (.env in CWD is loaded automatically):

PIPEFY_SERVICE_ACCOUNT_CLIENT_ID=your_client_id
PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET=your_client_secret
# Non-prod environments only:
# PIPEFY_BASE_URL=https://<your-api-host>
# PIPEFY_AUTH_URL=https://<your-signin-host>/realms/<realm>

PIPEFY_BASE_URL defaults to https://app.pipefy.com (drives the four API endpoints) and PIPEFY_AUTH_URL defaults to https://signin.pipefy.com/realms/pipefy (the OIDC issuer). Set them only for non-prod environments.

Authentication paths

Three credential sources, in CLI precedence order:

  1. Interactive (pipefy auth login) — browser OAuth flow, session stored in the OS keychain. Best for human developers. Status and revocation via pipefy auth status and pipefy auth logout.
  2. Static bearer (PIPEFY_TOKEN or --token) — direct bearer token, no OAuth. Intended for CI and scripted use. Overrides everything else.
  3. Service-account OAuth (PIPEFY_SERVICE_ACCOUNT_CLIENT_ID + PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET) — unattended OAuth client-credentials grant. Used by the MCP server.

Full env-var reference, validation rules, and config.toml precedence: docs/config.md. Auth deep-dive (precedence rules, troubleshooting, keychain backends): docs/cli/auth.md.

Output modes

Every command defaults to Rich-formatted human output. Add --json for machine-readable JSON to stdout.

pipefy card get 12345 --json | jq '.title'

Parity with MCP

Every MCP tool has a CLI counterpart (or a tracked deferral). See docs/parity.md for the full matrix.

Shell completion

pipefy --install-completion bash    # or zsh, fish, etc.

Development

From the repository root:

uv sync
uv run pytest packages/cli/tests     # CLI tests
uv run ruff check packages/cli/src   # lint

See AGENTS.md and CLAUDE.md for contributor guidance.