Delivery CLI

A command-line interface tool for interacting with the Delivery Locker Management Service. This tool provides platform operators with a simple, secure, and efficient way to manage delivery lockers, create reservations, and handle package drop-offs and pickups.

Features

🚀 Simple Configuration - Single env.config.json file, no complex profiles
🔧 AWS CLI Style Commands - Familiar noun-verb structure (e.g., get-machine, create-reservation)
📊 JSON-Only Output - Consistent output format, perfect for scripting
🐛 Powerful Debugging - Built-in --trace and --dump flags for troubleshooting
🌍 Cross-Platform - Works on Linux, macOS, and Windows
⚡ Zero Dependencies - Just download and run

Installation

Download Binary

Download the latest release (v1.0.6) for your platform:

Linux (AMD64): delivery-cli-linux-amd64
Linux (ARM64): delivery-cli-linux-arm64
macOS (Intel): delivery-cli-darwin-amd64
macOS (Apple Silicon): delivery-cli-darwin-arm64
Windows (AMD64): delivery-cli-windows-amd64.exe

Download the latest release for your platform from the Releases page.

Linux

# AMD64
curl -L /downloads/delivery-cli/delivery-cli-linux-amd64.tar.gz | tar -xz
sudo mv delivery-cli-linux-amd64 /usr/local/bin/delivery-cli
sudo chmod +x /usr/local/bin/delivery-cli

# ARM64
curl -L /downloads/delivery-cli/delivery-cli-linux-arm64.tar.gz | tar -xz
sudo mv delivery-cli-linux-arm64 /usr/local/bin/delivery-cli
sudo chmod +x /usr/local/bin/delivery-cli

macOS

# Intel
curl -L /downloads/delivery-cli/delivery-cli-darwin-amd64.tar.gz | tar -xz
sudo mv delivery-cli-darwin-amd64 /usr/local/bin/delivery-cli
sudo chmod +x /usr/local/bin/delivery-cli

# Apple Silicon
curl -L /downloads/delivery-cli/delivery-cli-darwin-arm64.tar.gz | tar -xz
sudo mv delivery-cli-darwin-arm64 /usr/local/bin/delivery-cli
sudo chmod +x /usr/local/bin/delivery-cli

Windows

Download delivery-cli-windows-amd64.zip from the Releases page
Extract the ZIP file
Add the directory containing delivery-cli.exe to your PATH
Or move delivery-cli.exe to a directory already in your PATH

Verify Installation

delivery-cli --version
# Output: delivery/v1.0.0 Linux/x86_64 Go/1.21.0

Quick Start

1. Configure API Access

Create a configuration file env.config.json in your current directory:

{
  "api_key": "your-api-key-here",
  "api_url": "https://api.delivery.kioskforce.com",
  "webhook_url": "https://your-webhook-endpoint.com/delivery"
}

Alternatively, use environment variables:

export DELIVERY_API_KEY=your-api-key-here
export DELIVERY_API_URL=https://api.delivery.kioskforce.com
export DELIVERY_WEBHOOK_URL=https://your-webhook-endpoint.com/delivery

2. Test Connection

# Test API connectivity
delivery-cli echo --message "Hello, Delivery Service!"

3. Find Available Lockers

# Search for lockers within 5km of a location
delivery-cli search-machines \
  --latitude 40.7128 \
  --longitude -74.0060 \
  --radius 5000 \
  --only-available-lockers

# Filter results with jq
delivery-cli search-machines \
  --latitude 40.7128 \
  --longitude -74.0060 \
  --radius 5000 | jq '.machines[] | {id: .machine.machine_id, distance: .distance_in_metres}'

4. Create a Reservation

# Create a reservation
delivery-cli create-reservation \
  --machine-id test-locker-001 \
  --platform-order-id ORD-2025-001 \
  --packaging '{"width":300,"height":300,"depth":300,"weight":2000}' \
  --notes "Fragile package" \
  --eta-minutes 30

# Extract reservation ID
RESERVATION_ID=$(delivery-cli create-reservation \
  --machine-id test-locker-001 \
  --platform-order-id ORD-2025-001 \
  --packaging '{"width":300,"height":300,"depth":300}' | jq -r '.reservation_id')

5. Handle Delivery

# Drop off package
delivery-cli dropoff --reservation-id $RESERVATION_ID

# Pick up package
delivery-cli pickup --reservation-id $RESERVATION_ID

Command Reference

Global Options

--config <file> - Path to config file (default: ./env.config.json)
--trace - Show HTTP request/response trace
--dump - Export as curl command
--version - Show version information
--help - Show help

Machine Commands

`get-machine`

Get details for a specific machine.

delivery-cli get-machine --machine-id <machine-id>

`search-machines`

Search for machines near a location.

delivery-cli search-machines \
  --latitude <lat> \
  --longitude <lon> \
  --radius <meters> \
  [--only-available-lockers] \
  [--packaging-width <mm>] \
  [--packaging-height <mm>] \
  [--packaging-depth <mm>] \
  [--limit <number>]

Reservation Commands

`create-reservation`

Create a new reservation.

delivery-cli create-reservation \
  --machine-id <machine-id> \
  --platform-order-id <order-id> \
  --packaging '{"width":300,"height":300,"depth":300}' \
  [--notes <string>] \
  [--eta-minutes <number>] \
  [--webhook-url <url>]

`get-reservation`

Get reservation details.

delivery-cli get-reservation --reservation-id <reservation-id>

`cancel-reservation`

Cancel a reservation.

delivery-cli cancel-reservation --reservation-id <reservation-id>

`abandon-pickup`

Abandon a pickup.

delivery-cli abandon-pickup --reservation-id <reservation-id>

Delivery Commands

`dropoff`

Initiate package drop-off.

delivery-cli dropoff --reservation-id <reservation-id>

`pickup`

Initiate package pickup.

delivery-cli pickup --reservation-id <reservation-id>

Debugging

HTTP Trace

See full HTTP request/response:

delivery-cli --trace get-machine --machine-id test-001

# Output:
--> GET /api/delivery/external/v1/machines/test-001
--> Host: api.delivery.kioskforce.com
--> X-API-Key: your-***-here
--> Accept: application/json

<-- 200 OK
<-- Content-Type: application/json
<-- {"machine_id":"test-001",...}

Export as Curl

Get the equivalent curl command:

delivery-cli --dump create-reservation \
  --machine-id test-001 \
  --platform-order-id ORD-001 \
  --packaging '{"width":300,"height":300,"depth":300}'

# Output:
curl -X POST 'https://api.delivery.kioskforce.com/api/delivery/external/v1/reservations' \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{"machine_id":"test-001",...}'

Integration Examples

Bash Script Example

#!/bin/bash
# find-and-reserve.sh - Find nearest locker and create reservation

set -e

# Configuration
LAT=40.7128
LON=-74.0060
ORDER_ID="ORD-$(date +%s)"

# Find nearest available locker
echo "Finding nearest available locker..."
MACHINE_ID=$(delivery-cli search-machines \
  --latitude $LAT \
  --longitude $LON \
  --radius 5000 \
  --only-available-lockers \
  --limit 1 | jq -r '.machines[0].machine.machine_id')

if [ -z "$MACHINE_ID" ]; then
  echo "No available lockers found"
  exit 1
fi

echo "Found locker: $MACHINE_ID"

# Create reservation
echo "Creating reservation..."
RESERVATION=$(delivery-cli create-reservation \
  --machine-id "$MACHINE_ID" \
  --platform-order-id "$ORDER_ID" \
  --packaging '{"width":300,"height":300,"depth":300}')

RESERVATION_ID=$(echo "$RESERVATION" | jq -r '.reservation_id')
DROPOFF_CODE=$(echo "$RESERVATION" | jq -r '.drop_off_code')

echo "Reservation created!"
echo "Reservation ID: $RESERVATION_ID"
echo "Drop-off code: $DROPOFF_CODE"

Python Integration

#!/usr/bin/env python3
import subprocess
import json

def run_delivery_cli(command, **kwargs):
    """Run delivery-cli command and return JSON output."""
    cmd = ['delivery-cli', command]
    
    for key, value in kwargs.items():
        cmd.extend([f'--{key.replace("_", "-")}', str(value)])
    
    result = subprocess.run(cmd, capture_output=True, text=True, check=True)
    return json.loads(result.stdout)

# Search for machines
machines = run_delivery_cli('search-machines',
    latitude=40.7128,
    longitude=-74.0060,
    radius=5000,
    only_available_lockers=True
)

# Get first available machine
if machines['machines']:
    machine_id = machines['machines'][0]['machine']['machine_id']
    
    # Create reservation
    reservation = run_delivery_cli('create-reservation',
        machine_id=machine_id,
        platform_order_id='PYTHON-001',
        packaging='{"width":300,"height":300,"depth":300}'
    )
    
    print(f"Created reservation: {reservation['reservation_id']}")

Node.js Integration

const { execSync } = require('child_process');

function deliveryCli(command, options = {}) {
  const args = [command];
  
  Object.entries(options).forEach(([key, value]) => {
    const flag = key.replace(/_/g, '-');
    args.push(`--${flag}`, value);
  });
  
  const output = execSync(`delivery-cli ${args.join(' ')}`, { encoding: 'utf8' });
  return JSON.parse(output);
}

// Search for machines
const machines = deliveryCli('search-machines', {
  latitude: 40.7128,
  longitude: -74.0060,
  radius: 5000,
  'only-available-lockers': true
});

// Create reservation
if (machines.machines.length > 0) {
  const machineId = machines.machines[0].machine.machine_id;
  
  const reservation = deliveryCli('create-reservation', {
    'machine-id': machineId,
    'platform-order-id': 'NODE-001',
    packaging: JSON.stringify({ width: 300, height: 300, depth: 300 })
  });
  
  console.log(`Reservation created: ${reservation.reservation_id}`);
}

Error Handling

The CLI provides clear error messages and appropriate exit codes:

0 - Success
1 - General error
2 - Configuration error
3 - Network/API error
4 - Invalid input

Example error handling in scripts:

#!/bin/bash
if ! delivery-cli get-machine --machine-id test-001; then
  echo "Failed to get machine details"
  exit 1
fi

Configuration Precedence

Configuration is loaded in the following order (highest precedence first):

Command-line flags
Environment variables
Configuration file (env.config.json)

API Endpoints

The CLI interacts with the following API endpoints:

Base URL: https://api.delivery.kioskforce.com
Authentication: X-API-Key header
All requests use JSON with snake_case field names

For complete API documentation, see the API Specification.

Troubleshooting

Common Issues

API Key not configured
```
Error: API key not configured
```
Solution: Set DELIVERY_API_KEY or add to env.config.json
Network connection failed
```
Error: Failed to connect to API server
```
Solution: Check network connection and API URL configuration
Machine not found
```
Error: Machine 'invalid-id' not found
```
Solution: Use search-machines to find valid machine IDs

Debug Mode

Enable detailed logging:

# Show HTTP traces
delivery-cli --trace <command>

# Export as curl for manual testing
delivery-cli --dump <command>

Building from Source

If you want to build the CLI from source:

# Clone the repository
git clone https://github.com/vendingontrack/delivery-cli.git
cd delivery-cli

# Install dependencies
go mod download

# Build for current platform
make build

# Build for all platforms
make build-all

# Run tests
make test

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

License

This software is proprietary and licensed for use by authorized platforms only.

Support

For support and questions:

Create an issue on GitHub
Contact your platform integration specialist

For more detailed documentation, see the main README.md file.

Features​

Installation​

Download Binary​

Linux​

macOS​

Windows​

Verify Installation​

Quick Start​

1. Configure API Access​

2. Test Connection​

3. Find Available Lockers​

4. Create a Reservation​

5. Handle Delivery​

Command Reference​

Global Options​

Machine Commands​

get-machine​

search-machines​

Reservation Commands​

create-reservation​

get-reservation​

cancel-reservation​

abandon-pickup​

Delivery Commands​

dropoff​

pickup​

Debugging​

HTTP Trace​

Export as Curl​

Integration Examples​

Bash Script Example​

Python Integration​

Node.js Integration​

Error Handling​

Configuration Precedence​

API Endpoints​

Troubleshooting​

Common Issues​

Debug Mode​

Building from Source​

Contributing​

License​

Support​