Deployment Guide

This guide walks you through deploying pycli-backed services to a production environment. You'll learn how to configure and run the CLI to deploy stacks across regions, and how to interact with the HTTP API to manage orders in production. Following these steps ensures your deployment is reproducible, correctly configured, and ready to serve live traffic.

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

• Python — required to run the pycli CLI tool
• pip — for installing pycli and its dependencies
• curl (or an equivalent HTTP client) — for interacting with the REST API
• Network access to your target API host (e.g., https://api.example.com)
• A valid deployment region identifier (e.g., us-east-1, us-west-2)
• Familiarity with basic HTTP concepts (request methods, JSON payloads, status codes)

Follow these steps to install pycli and verify it is ready to use.

1. Install pycli via pip:

   Copy

   pip install pycli
   

2. Verify the installation by checking the CLI is available:

   Copy

   pycli --help
   

   You should see the top-level help output listing the deploy and config commands.

3. Confirm the API service is reachable by sending a test request to your target host:

   Copy

   curl https://api.example.com/orders
   

   A 200 OK response with a JSON body confirms the API is up and accepting requests.

pycli exposes two primary configuration surfaces: CLI flags passed at invocation time, and persistent key-value settings managed through the config set subcommand.

CLI flags

Persistent configuration

Use pycli config set to store configuration values that persist across invocations. The flag --value accepts the value to assign, and the positional argument is the dot-separated configuration key.

pycli config set --value=<value> <key>

For example, setting retry.count controls how many times the tool retries a failed operation — a useful tuning knob in unstable network environments:

pycli config set --value=42 retry.count

Deploying a stack

To deploy a stack to production, provide the required --region flag and specify the target environment as a positional argument:

pycli deploy --region us-east-1 production

This tells pycli to deploy the production stack to the us-east-1 region. Use this as your standard production deployment command.

Previewing a deployment

Before pushing changes to production, run with --dry-run to see what would happen without making any real changes:

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

This is especially useful in pull-request pipelines where you want to validate configuration without affecting live infrastructure.

Managing configuration

Adjust persistent settings using config set. This is useful for tuning runtime behavior without modifying code:

pycli config set --value=42 retry.count

Interacting with the HTTP API

Once your service is running, you manage orders through the REST API. All requests are JSON over HTTP. The base URL in these examples is https://api.example.com.

Create an order — POST a JSON body containing amount (integer) and currency (string):

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

List orders — GET /orders with optional query parameters to filter results:

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

Fetch a single order — GET /orders/{order_id}:

curl https://api.example.com/orders/42

Cancel an order — DELETE /orders/{order_id}:

curl -X DELETE https://api.example.com/orders/42

Deploy the production stack to us-east-1

A standard production deployment targeting the US East region.

pycli deploy --region us-east-1 production

Preview a staging deployment without making changes

Use --dry-run to validate your configuration before promoting to production.

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

Set the retry count configuration key

Persist a configuration value across future CLI invocations.

pycli config set --value=42 retry.count

Create a new order via the API

Post a new order with an amount of 1500 USD.

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

Expected response (201 Created):

List paid orders (with limit)

Retrieve up to 10 orders that have a paid status.

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

Fetch a single order by ID

Retrieve the details of order 42.

curl https://api.example.com/orders/42

Cancel an order

Delete (cancel) order 42. This action cannot be undone.

curl -X DELETE https://api.example.com/orders/42

Use the following reference to diagnose and resolve common problems.

Symptom: pycli: command not found when running any CLI command.

Likely cause: pycli was not installed, or the Python bin directory is not on your PATH.

Fix: Re-run pip install pycli and confirm the install location is included in your PATH. On some systems you may need to use pip3 or install with the --user flag and update PATH accordingly.

Symptom: pycli deploy fails with an error about an invalid or missing --region value.

Likely cause: The --region flag is required and must be one of the accepted enum values. Passing an unsupported region string or omitting the flag entirely will cause the command to reject the input.

Fix: Ensure you pass --region with a supported value (e.g., us-east-1, us-west-2). Consult your team's region registry for the full list of accepted identifiers.

Symptom: A POST /orders request returns a 422 Unprocessable Entity response.

Likely cause: The request body does not conform to the expected schema. The API requires both amount (integer) and currency (string) fields.

Fix: Verify your request body is valid JSON and includes both required fields. For example:

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

Also confirm the Content-Type: application/json header is present — omitting it can cause the server to reject the body.

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

Likely cause: The specified order_id does not exist, has already been cancelled/deleted, or the wrong ID is being used.

Fix: Confirm the order ID by listing current orders first:

curl 'https://api.example.com/orders'

Then retry the request with a valid ID from the response.

Symptom: curl requests to the API return a connection error or timeout.

Likely cause: The API host is unreachable. This may be a network issue, an incorrect base URL, or the service not being deployed.

Fix: Verify the target URL is correct and that your environment has outbound HTTP access to the host. Check that the pycli API service is deployed and healthy before retrying.