Development Guide

This guide walks you through setting up a local development environment for pycli and verifying that both surfaces — the CLI and the HTTP API — work correctly on your machine. Getting this environment right lets you iterate quickly on stack deployments and order management workflows before pointing at a production endpoint. By the end of this guide you will have pycli installed, the API server running locally, and a working set of example requests you can use as a baseline for your own integration work.

Before you begin, make sure you have the following in place:

• Python 3.10 or higher — pycli requires python >= 3.10. Run python --version to confirm.
• pip — used to install the package and its dependencies. Any version compatible with your Python 3.10+ installation is sufficient.
• curl (or an HTTP client of your choice) — the examples in this guide use curl to exercise the API endpoints directly.
• A terminal — all commands are run from a shell prompt.

Follow these steps to install pycli and start the local API server.

1. Clone or download the project source.

   Copy

   git clone <repository-url>
   cd pycli
   

2. Create and activate a virtual environment (recommended to keep dependencies isolated).

   Copy

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install the package and its dependencies.

   Copy

   pip install .
   

   This installs the three runtime dependencies declared in pyproject.toml:

   • click >= 8.0 — powers the pycli CLI entry point
   • fastapi >= 0.110 — powers the HTTP API
   • pydantic >= 2.0 — validates request bodies

4. Verify the CLI entry point is available.

   Copy

   pycli --help
   

   You should see the top-level help output listing the available commands.

5. Start the API server locally.

   Copy

   uvicorn api:app --reload
   

   Note for reviewer: The source material does not mention uvicorn as a dependency, nor does it document a local server start command. The uvicorn invocation above is the conventional way to run a FastAPI app named api:app, but you should confirm the correct start command and add uvicorn to the dependency list if it is required.

   Once running, the API is reachable at http://localhost:8000 by default.

pycli exposes configuration through CLI flags rather than a separate config file. The table below describes the options that affect runtime behavior.

Why --region matters: the region flag is an enum-validated input, meaning pycli will reject values that are not in its allowed set and return an error before any deployment work begins. This lets you catch environment mismatches early.

Why --dry-run matters: use this flag during development to verify that your command arguments and stack name are correct without incurring the cost or side effects of a real deployment.

Once pycli is installed and the API server is running, you will interact with two surfaces: the pycli CLI for deployment and configuration tasks, and the HTTP API for order management.

Deploying a stack

Use pycli deploy to deploy a named stack to a specific region. The --region flag is required and must be a valid enum value.

pycli deploy --region us-east-1 production

Before committing to a deployment, use --dry-run to preview what would happen without applying changes:

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

Setting a configuration value

Use pycli config set to write a value to a named configuration key. The key is a positional argument and --value is required.

pycli config set --value=42 retry.count

Working with the orders API

All order operations go through the HTTP API. During local development, replace https://api.example.com with http://localhost:8000 in every request.

• Create an order — POST to /orders with a JSON body.
• List orders — GET /orders, optionally filtering by status and paginating with limit.
• View a single order — GET /orders/{order_id}.
• Cancel an order — DELETE /orders/{order_id}.

See the Examples section below for runnable curl commands for each operation.

All examples below target the local development server at http://localhost:8000. Substitute https://api.example.com when working against a remote environment.

Deploy a stack to production

pycli deploy --region us-east-1 production

Preview a staging deployment without applying changes

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

Set a configuration value

pycli config set --value=42 retry.count

Create an order

curl -X POST http://localhost:8000/orders \
  -H 'Content-Type: application/json' \
  -d '{"amount": 1500, "currency": "USD"}'

Expected response (HTTP 201 or 200):

{
  "id": 1,
  "amount": 1500,
  "currency": "USD",
  "status": "pending"
}

List orders filtered by status

curl 'http://localhost:8000/orders?status=paid&limit=10'

Expected response: a JSON array of order objects matching the paid status, capped at 10 results.

View a single order

curl http://localhost:8000/orders/42

Expected response: a JSON object representing order 42, or a 404 error if the order does not exist.

Cancel an order

curl -X DELETE http://localhost:8000/orders/42

Expected response: a confirmation that the order has been cancelled, or a 404 error if the order does not exist.

Use the following reference to diagnose common problems during local development.

Symptom: pycli: command not found after installation.

Likely cause: The virtual environment is not activated, or the pip install . step did not complete successfully.

Fix: Activate your virtual environment (source .venv/bin/activate) and re-run pip install .. Confirm the entry point exists with which pycli.

Symptom: pycli deploy exits with an error about an invalid value for --region.

Likely cause: You passed a region string that is not in pycli's allowed enum set (for example, a typo or an unsupported region).

Fix: Use one of the documented valid values for --region. Refer to the Configuration section for the supported list.

Symptom: curl returns Connection refused when targeting http://localhost:8000.

Likely cause: The API server is not running, or it started on a different port.

Fix: Start the server with uvicorn api:app --reload and confirm it is listening on port 8000. Check the terminal output for the bound address.

Symptom: POST /orders returns HTTP 422 Unprocessable Entity.

Likely cause: The request body is missing a required field or contains a value of the wrong type. pycli uses Pydantic to validate the CreateOrderBody schema, so any structural mismatch will be rejected.

Fix: Ensure your JSON body includes all required fields with the correct types. The minimum required fields shown in the documentation are amount (number) and currency (string).

Symptom: GET /orders/{order_id} or DELETE /orders/{order_id} returns HTTP 404.

Likely cause: The order ID does not exist in the current dataset, or you are targeting the wrong environment.

Fix: Verify the order ID by calling GET /orders first to list available orders, and confirm you are pointing at the correct host.