Configuration

This page explains how to configure pycli for your environment before deploying stacks or making API calls. Configuration controls runtime behavior such as target region, deployment mode, and key-value settings that your stacks and services depend on. Getting configuration right ensures that both the CLI and the HTTP API behave predictably across environments. If you are new to pycli, read this page before running your first deploy or order request.

Before configuring pycli, make sure you have the following in place:

• Python 3.10 or later — pycli requires python >= 3.10
• pycli installed — see the Installation section below
• Network access to your API host — required for any HTTP API interaction
• A valid API endpoint URL — for example, https://api.example.com

Follow these steps to install pycli and its dependencies.

1. Ensure Python 3.10+ is available:

   Copy

   python --version
   

   You should see Python 3.10.x or higher.

2. Install pycli using pip:

   Copy

   pip install pycli
   

   This installs pycli along with its required dependencies: click >= 8.0, fastapi >= 0.110, and pydantic >= 2.0.

3. Verify the installation:

   Copy

   pycli --help
   

   You should see the pycli help output listing available commands such as deploy and config.

pycli exposes configuration through the config set subcommand, which writes key-value pairs used at deploy time and by the API layer.

Setting a configuration value

Use pycli config set to define a named key with a value:

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

Deployment flags

When running pycli deploy, two flags affect deployment behavior:

API base URL

All HTTP API calls are made against your configured host. In the examples throughout this documentation, https://api.example.com is used as a placeholder. Replace this with the actual URL of your deployed API server.

The following patterns represent the most common configuration tasks you will perform with pycli.

Setting a configuration key

Use dot-notation keys to organize configuration logically. For example, to set a retry count:

pycli config set --value=42 retry.count

This stores retry.count = 42 in your local pycli configuration. Your stack deployment will pick this value up at runtime.

Deploying to a specific region

Pass --region to target a particular environment. This flag is required and accepts an enum of valid region identifiers:

pycli deploy --region us-east-1 production

Substitute production with your stack name, and us-east-1 with your intended region.

Previewing a deployment before applying

Before committing a deployment, use --dry-run to validate your configuration without making any changes:

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

This is particularly useful when you have just changed a configuration value and want to confirm the deployment plan looks correct.

Configuring requests to the HTTP API

Pycli's HTTP API does not require the CLI to be installed on the client side — you can interact with it using any HTTP client such as curl. Set the Content-Type header to application/json whenever you send a request body:

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

Each example below is self-contained and runnable. Replace https://api.example.com with your actual API host.

Set a configuration value before deploying

pycli config set --value=42 retry.count

Expected output:

Configuration updated: retry.count = 42

Deploy a stack to us-east-1

pycli deploy --region us-east-1 production

Expected output:

Deploying stack 'production' to region 'us-east-1'...
Done.

Preview a deployment with dry-run

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

Expected output:

[dry-run] Would deploy stack 'staging' to region 'us-west-2'. No changes applied.

Create an order via the HTTP API

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

Expected response:

{
  "order_id": 42,
  "amount": 1500,
  "currency": "USD",
  "status": "pending"
}

List orders filtered by status

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

Expected response:

[
  {
    "order_id": 42,
    "amount": 1500,
    "currency": "USD",
    "status": "paid"
  }
]

Use the following reference to diagnose and fix common configuration and deployment problems.

Problem: pycli: command not found after installation

• Symptom: Running pycli --help returns a shell error indicating the command is not found.
• Likely cause: The Python bin or Scripts directory is not in your PATH, or installation completed in a virtual environment that is not activated.
• Fix: Activate your virtual environment (source .venv/bin/activate on Unix, .venv\Scripts\activate on Windows) or add the relevant Python scripts directory to your PATH.

Problem: deploy fails with an invalid region error

• Symptom: Running pycli deploy --region <value> <stack> returns an error indicating the region value is not accepted.
• Likely cause: The --region flag accepts a fixed enum of values. Passing an unrecognized string (e.g., a typo or unsupported region) causes validation to fail immediately.
• Fix: Check the valid region values and use one of the accepted identifiers such as us-east-1 or us-west-2.

Problem: HTTP API returns 422 Unprocessable Entity on POST /orders

• Symptom: A curl POST to /orders returns a 422 response with a validation error body.
• Likely cause: The request body is missing required fields or contains incorrectly typed values. The API uses Pydantic validation, so both field presence and type are enforced.
• Fix: Ensure your request body includes all required fields with correct types. For example: {"amount": 1500, "currency": "USD"}. Also verify the Content-Type: application/json header is present.

Problem: pycli config set does not appear to affect deployment behavior

• Symptom: You set a key with config set, but the subsequent deploy command does not reflect the new value.
• Likely cause: The config key name may be misspelled, or the deployment command may be reading from a different configuration source (e.g., environment variables or a separate config file) with higher precedence.
• Fix: Double-check the exact key name used with config set. Verify that no environment variable or higher-precedence config file is overriding the value.

Problem: curl requests to the API time out or return connection errors

• Symptom: HTTP requests to https://api.example.com hang or return Could not resolve host / Connection refused.
• Likely cause: The API server is not running, the host URL is incorrect, or network/firewall rules are blocking access.
• Fix: Confirm the API server is running and accessible from your machine. Replace the example host https://api.example.com with your actual deployed API URL.