Skip to main content

Client & CLI Tools

Client & CLI Tools​

Client & CLI Tools provide a unified interface for interacting with the platform, enabling both programmatic automation and direct command-line management. These tools are designed to streamline development workflows, facilitate integration with existing systems, and offer robust control over platform resources.

Purpose​

The primary purpose of Client & CLI Tools is to offer developers a consistent and efficient means to manage, configure, and interact with the platform's services and data. This includes automating routine tasks, scripting complex operations, and providing immediate feedback on system status, thereby accelerating development and operational efficiency.

Core Capabilities​

The Client & CLI Tools offer a comprehensive set of capabilities, encompassing programmatic access via a client library and interactive management through a command-line interface.

Programmatic Client​

The client library provides a Pythonic interface for interacting with the platform's APIs. It abstracts underlying network communication and API specifics, allowing developers to focus on business logic.

  • Resource Management: Create, retrieve, update, and delete platform resources (e.g., client.resources.create(...), client.resources.get("resource_id")).
  • Data Operations: Perform data ingestion, querying, and manipulation (e.g., client.data.query("SELECT * FROM ..."), client.data.upload(file_path)).
  • Service Invocation: Directly call platform services and functions (e.g., client.services.invoke("service_name", payload)).
  • Asynchronous Operations: Support for non-blocking operations, crucial for high-performance applications. The client library integrates with asyncio, allowing methods like await client.resources.async_create(...) for concurrent execution.

Example: Creating a Resource Programmatically

from my_platform_client import Client

# Initialize the client, typically configured via environment variables or a config file
client = Client()

try:
    new_resource = client.resources.create(
        name="my-new-resource",
        type="compute",
        config={"cpu": 2, "memory_gb": 4}
    )
    print(f"Resource '{new_resource.name}' created with ID: {new_resource.id}")

    # Retrieve the resource
    retrieved_resource = client.resources.get(new_resource.id)
    print(f"Retrieved resource status: {retrieved_resource.status}")

except Exception as e:
    print(f"Error creating resource: {e}")

Command-Line Interface​

The CLI tool provides a powerful, scriptable interface for direct interaction with the platform. It mirrors much of the functionality available in the programmatic client, optimized for shell environments.

  • Configuration Management: Set up and manage platform configurations, profiles, and credentials (e.g., cli config set region us-east-1).
  • Resource Lifecycle: Manage the full lifecycle of resources, from creation to deletion (e.g., cli resource create --name my-app --type web, cli resource delete my-app).
  • Monitoring and Logging: Retrieve logs, metrics, and status information for resources and services (e.g., cli logs stream my-service, cli metrics get my-resource --period 1h).
  • Output Formatting: Supports various output formats, including human-readable tables, JSON, and YAML, facilitating integration with other command-line tools (e.g., cli resource list --output json | jq .).

Example: Managing Resources via CLI

# Authenticate and configure the CLI (if not already done)
cli auth login

# List existing resources
cli resource list

# Create a new resource
cli resource create --name my-database --type database --config '{"engine": "postgres", "version": "14"}'

# Get details for a specific resource
cli resource get my-database --output yaml

# Update a resource configuration
cli resource update my-database --config '{"engine": "postgres", "version": "15"}'

# Delete a resource
cli resource delete my-database --force

Authentication and Configuration​

Both the client library and the CLI tool leverage a unified authentication and configuration mechanism. This typically involves:

  • API Keys/Tokens: Securely manage credentials, often via environment variables (PLATFORM_API_KEY) or a dedicated configuration file (~/.platform/config).
  • Profiles: Support for multiple named profiles, allowing easy switching between different environments or accounts (e.g., cli --profile dev resource list).
  • Session Management: The client library handles token refreshing and session persistence automatically.

Error Handling and Logging​

Robust error handling is integrated into both interfaces. The client library raises specific exceptions for API errors (e.g., ResourceNotFoundException, AuthenticationError), allowing for precise error management in code. The CLI tool provides clear error messages and exit codes, suitable for scripting and CI/CD pipelines. Comprehensive logging capabilities are available, configurable for different verbosity levels.

Common Use Cases​

  • Automated Deployments: Integrate the CLI tool into CI/CD pipelines to provision infrastructure, deploy applications, and manage service configurations automatically.
  • Data Processing Workflows: Use the programmatic client to script complex data ingestion, transformation, and analysis tasks, integrating with existing Python data pipelines.
  • Interactive Resource Management: Developers and operators use the CLI tool for ad-hoc queries, debugging, and managing resources directly from their terminals.
  • Custom Tooling and Dashboards: Build custom applications, monitoring dashboards, or internal tools using the client library to interact with platform services.
  • Backup and Recovery: Script regular backups of critical data and configurations using the CLI tool or client library, and automate recovery procedures.

Integration Patterns and Best Practices​

  • Idempotent Operations: When scripting with the CLI or client, design operations to be idempotent where possible. This ensures that repeated execution of a script does not lead to unintended side effects or resource duplication.
  • Error Handling: Always implement robust error handling in programmatic integrations. Catch specific exceptions from the client library to differentiate between transient network issues and API-specific errors. For CLI scripts, check exit codes ($? in bash) to determine command success or failure.
  • Configuration Management: Centralize configuration using environment variables or dedicated configuration files. Avoid hardcoding sensitive information. The client library automatically picks up credentials from standard locations or environment variables.
  • Batch Operations: For performance-critical tasks involving many resources, leverage batch operations provided by the client library (e.g., client.resources.batch_delete([...])) instead of individual calls to minimize API overhead.
  • Rate Limiting: Be aware of platform API rate limits. The client library often includes built-in retry mechanisms with exponential backoff, but for high-throughput applications, implement custom rate limiting or queueing.
  • Security: Follow the principle of least privilege. Configure API keys and user roles with only the necessary permissions for the tasks they perform.

Considerations and Limitations​

  • API Versioning: While the client library aims for backward compatibility, be mindful of API version changes. Consult release notes for potential breaking changes when upgrading the client library.
  • Network Latency: Operations involving remote services are subject to network latency. Design applications to be resilient to varying network conditions and consider asynchronous patterns for long-running tasks.
  • Resource Limits: The platform imposes various resource limits (e.g., maximum number of resources, data storage limits). The client library and CLI tool will report errors when these limits are exceeded.
  • Offline Capabilities: The tools primarily interact with the live platform. Limited offline capabilities exist for configuration management, but most operations require an active network connection.