Problem Being Solved

pycli is a tool for deploying infrastructure stacks and managing orders through two complementary surfaces: a command-line interface and an HTTP API. This page explains what problems pycli solves and why those two surfaces exist, so you can decide how to integrate pycli into your workflows before diving into setup and usage.

The core problem

Managing infrastructure deployments and order workflows often requires two different modes of interaction: interactive, scriptable commands you can run from a terminal, and programmatic endpoints you can call from application code or automation pipelines. Tools that cover only one of these force you to maintain separate systems—one for operators running deployments, another for services creating and tracking orders.

pycli addresses this by shipping both surfaces under a single product:

• A CLI for deployment and configuration tasks that operators typically run directly or embed in CI scripts.
• An HTTP API for order management that application code and integrations call at runtime.

What the CLI solves

Deploying a stack and tuning its configuration are inherently operator-driven tasks. You need to target a specific environment, choose a region, and optionally preview what will change before committing. The pycli CLI gives you a single command (deploy) with flags that make those choices explicit—including a dry-run mode so you can preview a deployment without applying it. A companion config set subcommand lets you update individual configuration values without redeploying the entire stack.

What the HTTP API solves

Order lifecycle management—creating orders, listing them by status, fetching a single record, or cancelling one—is better handled by an HTTP API than a CLI. Application code can call these endpoints directly, webhooks can trigger them, and automation can poll them without shelling out to a subprocess. The API accepts and returns JSON, making it straightforward to integrate with any HTTP client or service.

Why two surfaces instead of one

The CLI and the API serve different principals at different times. Operators interact with the CLI at deploy time; services and integrations interact with the API at runtime. Keeping them separate means each surface can be optimized for its audience—ergonomic flags and human-readable output for the CLI, structured JSON request and response bodies for the API—without compromise.

Check what a deployment would change before applying it

Passing --dry-run lets you preview which resources would be affected without making any real changes. Use this in pull-request pipelines to surface infrastructure diffs early.

pycli deploy --region us-west-2 --dry-run staging

Create an order via the API

Post a JSON body with the required fields to create a new order. The API validates the body shape before persisting the record.

curl -X POST https://api.example.com/orders \
  -H 'Content-Type: application/json' \
  -d '{"amount": 1500, "currency": "USD"}'

List orders filtered by status

You can narrow results using query parameters. The example below returns up to ten paid orders.

curl 'https://api.example.com/orders?status=paid&limit=10'

• Installing pycli — Get the CLI and API running in your environment before following any of the workflow guides.
• Deploying a stack — Step-by-step guide to the pycli deploy command, including all supported flags and environments.
• Setting a configuration value — How to use pycli config set to update individual settings without a full redeploy.
• Orders API reference — Full reference for the /orders and /orders/{order_id} endpoints, including request bodies, response schemas, and error codes.
• Authentication — How to authenticate requests to the HTTP API.