Command Line Interface (CLI)

The Pipelogic CLI tool ("ppl") is for building and deploying Pipelogic components. It lets you scaffold components, manage metadata, run tests, and automate deployment — all from a simple command-line interface.

The ppl CLI is designed to be user-friendly and requires only basic knowledge of the terminal.

Get started by installing the Pipelogic CLI ("ppl"):

curl -fsSL https:/app.pipelogic.ai/api/v1/install | bash

List of commands

This section provides a comprehensive reference for technical users looking to automate and scale their AI pipeline development using Pipelogic’s CLI. Terminal examples and expected outputs are included for every command.

We cluster commands into three categories:

Common commands — the most frequently used operations
Management commands — involve actions that modify, configure, or maintain core resources
Essential commands — required to operate and interact with the CLI tool effectively

capsuleMANAGEMENT COMMAND

Manage Capsules

Manage capsules — isolated compute environments for running pipelines.

Capsules represent containerized execution environments where pipeline components are deployed and executed. Capsules define the hardware, software stack, and runtime isolation for your pipelines. This command group provides tools to list, inspect, and manage available capsules.

Terminal Output

% ppl capsule -h

Usage:
  ppl capsule [command]

Available Commands:
  list        List all capsules available to your account or workspace

Flags:
  -h, --help  Show help for the capsule command group

Examples:
  ppl capsule list          # View all available capsules
  ppl capsule --help        # View capsule management options

Use "ppl capsule [command] --help" for detailed help on each subcommand.

capsulesCOMMON COMMAND

List Capsules

List all capsules available in your account.

Capsules are isolated compute environments used to deploy and execute pipelines. Each capsule is associated with a workspace and includes resource definitions such as CPU, memory, and GPU availability.

This command displays a table with capsule details including:

Capsule ID and name
Workspace name
Status (active, stopped, etc.)
Creation timestamp

Terminal Output

% ppl capsules -h

Usage:
  ppl capsules [flags]

Aliases:
  capsules, capsule list

Flags:
  -h, --help   Show help for this command

Examples:
  # List all capsules
  ppl capsules

compileCOMMON COMMAND

Compile Components

Compile the component source code to validate its build process.

This command performs a local dry-run build of the current component without releasing it to the platform. It is useful for verifying that your code compiles correctly before running tests or pushing a release.

Note: Tests are not executed during compilation.

Log verbosity levels:

none – No output
run – Show runtime logs only
build – Show build logs (default)
all – Show all logs (build, run, download, upload)

Terminal Output

% ppl compile -h

Usage:
  ppl compile [flags]

Flags:
  -h, --help               Show help for this command
  -o, --mode string        Compilation mode (e.g. debug, release)
  -q, --quiet              Suppress all logs
  -v, --verbosity string   Set log verbosity level (none|run|build|all) (default "build")

Examples:
  # Compile a component with default settings
  ppl compile

  # Compile with silent output
  ppl compile --quiet

  # Compile with full logs
  ppl compile -v all

completionESSENTIAL COMMAND

Shell Autocompletion

Generate shell autocompletion scripts for the ppl CLI.

The generated script enables command-line autocompletion for supported shells. You can source the script in your shell or add it to your shell configuration file (e.g., .bashrc, .zshrc) for persistent autocomplete support.

Available shells:

bash
zsh
fish
powershell

Terminal Output

% ppl completion -h

Usage:
  ppl completion [shell] [flags]

Subcommands:
  bash         Generate completion script for Bash
  zsh          Generate completion script for Zsh
  fish         Generate completion script for Fish
  powershell   Generate completion script for PowerShell

Flags:
  -h, --help   Show help for the completion command

Examples:
  ppl completion bash > /etc/bash_completion.d/ppl
  ppl completion zsh > "${fpath[1]}/_ppl"
  source <(ppl completion fish)

For detailed instructions, run:
  ppl completion <shell> --help

componentMANAGEMENT COMMAND

Manage Components

Manage Pipelogic components — the modular building blocks of pipelines.

Components encapsulate reusable logic and can be versioned, configured, and published to the platform. This command group allows for full lifecycle management of your components.

Key capabilities:

Create and initialize new components
View, update, or delete component metadata and versions
Transfer ownership across workspaces or users
Manage configuration and documentation

Terminal Output

% ppl component -h

Usage:
  ppl component [command] [flags]

Available Commands:
  create      Create and initialize a new component
  delete      Delete a component or a specific component version
  list        List all components accessible in the current workspace
  transfer    Transfer component ownership to another user or workspace
  update      Update component metadata, configuration, or tags
  versions    List all published versions of a component

Flags:
  -h, --help   Show help for the component command group

Examples:
  ppl component create
  ppl component update --id comp-abc123 --name "Updated Name"
  ppl component delete --id comp-abc123 --version 1.2.0
  ppl component transfer --id comp-abc123 --to user@example.com
  ppl component versions --id comp-abc123

Use "ppl component [command] --help" for more information on a specific subcommand.

componentsCOMMON COMMAND

List Components

List all components available in your workspace.

Displays a table of components you own or have access to, including metadata such as:

Component name and unique identifier
Programming language and tags
Creation and last update timestamps
Status (e.g., draft, released)

Components are sorted by creation date (most recent first). Use this command to browse available components for reuse, inspection, or modification.

Terminal Output

% ppl components -h

Usage:
  ppl components [flags]

Aliases:
  components, component list

Flags:
  -h, --help   Show help for this command

Examples:
  # Show all components you have access to
  ppl components

containerMANAGEMENT COMMAND

Manage Containers

Administrative commands for managing containers within a deployment.

Supports advanced operations such as:

Listing containers and their statuses
Retrieving logs from specific containers
Inspecting container state and network information

Terminal Output

% ppl container -h

Usage:
  ppl container [command] [flags]

Available Commands:
  list        List all containers in a deployment
  logs        Fetch logs from a specific container

Flags:
  -h, --help   Show help for the 'container' command

Examples:
  ppl container list --deployment <deployment_id>
  ppl container logs <container_id>

Use "ppl container [command] --help" for more information about a specific command.

containersCOMMON COMMAND

List Containers

List all containers running within a deployment.

Displays a structured overview of container instances in a pipeline deployment, including metadata, status, health, and runtime details.

Information shown:

Container ID and name
Associated component
Runtime status and health checks
CPU and memory usage
Port bindings and network configuration

Filters:

Specify a deployment ID to target a specific pipeline deployment
Optionally filter further by capsule ID

If no deployment is provided, you will be prompted to select one interactively.

Terminal Output

% ppl containers -h

Usage:
  ppl containers [flags]

Aliases:
  containers, container list

Flags:
  -d, --deployment string   Filter containers by deployment ID
  -c, --capsule string      Filter containers by capsule ID
  -h, --help                Show help for this command

Examples:
  # List containers in a specific deployment
  ppl containers -d deploy-123

  # List containers running in a capsule within a deployment
  ppl containers -d deploy-123 -c capsule-xyz

debugCOMMON COMMAND

Debug Deployments

Launch an interactive debugging session for a deployment.

Enables comprehensive inspection and real-time troubleshooting for a specific deployment.

Features include:

Live container logs with real-time streaming
Container and component health inspection
Dependency graph visualization and analysis
Network reachability testing across components
Resource usage and performance metrics

Use this tool to identify issues, optimize runtime behavior, and debug misconfigurations within deployed pipelines.

Terminal Output

% ppl debug -h

Usage:
  ppl debug <deployment_id> [flags]

Aliases:
  debug, deployment debug

Flags:
  -h, --help   Show help for this command

Examples:
  # Launch debug session for deployment
  ppl debug 02fb839a-d5de-4fbc-b15e-bf580ea8d5d1

deployCOMMON COMMAND

Deploy Pipelines

Deploy a pipeline for execution within a specified capsule environment.

This command provisions the required compute resources, sets up all pipeline components, configures stream connections, and starts the execution process. Each deployment is assigned a unique ID, which can be used for monitoring, management, and logs retrieval.

You can optionally launch in debug mode or run interactively to inspect live data and component states during execution.

Terminal Output

% ppl deploy -h

Usage:
  ppl deploy [flags]

Aliases:
  deploy, pipeline deploy

Flags:
  -p, --pipeline <id>      Pipeline ID to deploy (required)
  -c, --capsule <id>       Capsule ID that defines the infrastructure profile
  -d, --debug              Enable verbose logging and diagnostics
  -i, --interactive        Enter interactive session post-deployment (for debugging)
  -h, --help               Show this help message and exit

Examples:
  # Deploy pipeline to a capsule
  ppl deploy -p e61a710e-e55e-4d6a-afc3-ee487636d403 -c ed7b32da-da7b-4501-9c84-4953cfca29c0

  # Deploy with debug logging
  ppl deploy -p e61a710e-e55e-4d6a-afc3-ee487636d403 -c ed7b32da-da7b-4501-9c84-4953cfca29c0 --debug

  # Launch interactive session after deploy
  ppl deploy -p e61a710e-e55e-4d6a-afc3-ee487636d403 -c ed7b32da-da7b-4501-9c84-4953cfca29c0 --interactive

deploymentMANAGEMENT COMMAND

Manage Deployments

Manage pipeline deployments and monitor their lifecycle.

The deployment command group provides tools to inspect, debug, and analyze the health, performance, and resource usage of running or historical pipeline deployments.

Key features:

List and inspect active or completed deployments
Stream metrics and statistics for performance analysis
Launch interactive debugging sessions for troubleshooting

Terminal Output

% ppl deployment -h

Usage:
  ppl deployment [command] [flags]

Available Commands:
  debug       Start an interactive debugging session for a specific deployment
  list        Display all deployments across capsules and workspaces
  stats       Show performance metrics and resource usage for a deployment

Flags:
  -h, --help   Show help for the deployment command group

Examples:
  ppl deployment list
  ppl deployment debug <deployment_id>
  ppl deployment stats <deployment_id>

Use "ppl deployment [command] --help" for more information about a specific subcommand.

deploymentsCOMMON COMMAND

List Deployments

List pipeline deployments across capsules.

Displays a centralized overview of current and historical deployments, including key metadata and runtime information.

Details shown per deployment:

Deployment ID and name
Status (e.g., running, stopped, failed)
Associated pipeline and capsule
Created/updated timestamps
Lifecycle stage (e.g., initializing, running, terminating)
Allocated compute resources
Component health and status summary

This command is useful for monitoring, auditing, and managing active and past pipeline deployments across all environments.

Terminal Output

% ppl deployments -h

Usage:
  ppl deployments [flags]

Flags:
  -c, --capsule <capsule_id>   Filter deployments by specific capsule ID
  -h, --help                   Show help for this command

Examples:
  # List all deployments
  ppl deployments

  # List deployments filtered by capsule
  ppl deployments --capsule abc123-capsule

fileMANAGEMENT COMMAND

Manage Files

Manage and organize files for machine learning workflows.

The file command group enables uploading, downloading, and managing a wide range of file types, including:

Machine learning models with optional configuration files
Datasets for training and inference
Video, audio, and image assets
Custom artifacts required by pipeline components

Files can be reused across projects, shared within teams, and versioned appropriately. Access control and ownership transfer are supported.

Terminal Output

% ppl file -h

Usage:
  ppl file [command]

Available Commands:
  upload      Upload a file or folder to the platform
  download    Download a file from the platform
  update      Modify file metadata, add README or configuration files
  delete      Permanently delete a file from your workspace
  transfer    Transfer ownership of a file to another user or workspace
  list        List files you own or have access to

Flags:
  -h, --help   Show help for the file command group

Examples:
  ppl file upload model.onnx
  ppl file update <file_id> --readme README.md
  ppl file list
  ppl file transfer <file_id> --to my-team

Use "ppl file [command] --help" to learn more about a specific subcommand.

filesCOMMON COMMAND

List Files

List available files in your Pipelogic workspace.

Displays a table of all files you own or have been granted access to, along with detailed metadata.

For each file, the following information is shown:

File ID and name
File type (e.g., video, model, dataset)
Upload timestamp
File size
Owner and permission level
Associated tags and metadata

Use this command to browse available inputs (e.g., videos or models), manage datasets, or review previously uploaded files.

Terminal Output

% ppl files -h

Usage:
  ppl files [flags]

Aliases:
  files, file list

Flags:
  -h, --help   Show help for this command

Examples:
  # List all accessible files
  ppl files

gentypesCOMMON COMMAND

Generate Type Definitions

Generate type definitions for use in component code.

This command creates language-specific type files based on the component configuration, pipeline schemas, and any additional types you specify. These definitions improve type safety and ensure correct data handling across your pipeline.

What it does:

Extracts types from:
- Component input/output interfaces
- Pipeline definitions
- Manually specified custom types
Generates:
- Python: pipetypes.py
  - Type classes, validation, serialization
- C++: pipetypes.hpp
  - Type structs, converters, serialization helpers
Writes output into the src/ folder of the component

Terminal Output

% ppl gentypes -h

Usage:
  ppl gentypes [flags]

Flags:
  -h, --help   Show help for this command

Examples:
  # Generate types from config
  ppl gentypes

helpESSENTIAL COMMAND

Help

Display help information for any command.

You can view general help or get detailed usage for a specific subcommand by appending its path: ppl help <command>.

Terminal Output

% ppl help -h

Usage:
  ppl help [command] [flags]

Flags:
  -h, --help   Show help for the help command

Examples:
  ppl help init
  ppl help pipeline deploy

initCOMMON COMMAND

Initialize Codebases

Sets up a new Pipelogic component codebase.

Create a new component using a template with boilerplate code, or initialize an existing component from its Component ID.

Terminal Output

% ppl init -h

Usage:
  ppl init [flags]

Flags:
  -t, --template            Create a new component from a template
  -c, --component <id>      Initialize an existing component using its Component ID
  -h, --help                Show help for this command

Directory Structure Created:
  component/
  ├── component.yml         # Metadata and configuration
  ├── src/                  # Source code for your component
  ├── tests/                # Unit tests with input/output examples
  └── assets/               # Optional: static files or model files

Examples:
  # Create a new component from template
  ppl init -t

  # Initialize an existing component by ID
  ppl init -c 2eaea124-de2e-4d7f-b6cd-c3cac94e29b3

loginESSENTIAL COMMAND

Log In

Authenticate with the active Pipelogic remote server.

You can log in by supplying credentials via flags or through an interactive prompt. After successful authentication, you'll either enter the specified workspace or be prompted to select one.

⚠️ Security Tip: Avoid using --password in shared terminals or scripts to prevent credential exposure.

Terminal Output

% ppl login -h

Usage:
  ppl login [flags]

Flags:
  -u, --user string          Username or email for authentication
  -p, --password string      Password for authentication
                            (not recommended in scripts or shared environments)
      --workspace string     ID of the workspace to enter after login.
                            If omitted, your last used workspace will be selected automatically,
                            or you’ll be prompted to choose one during first-time login.
  -h, --help                 Show help for this command

logoutESSENTIAL COMMAND

Log Out

Log out from the currently active remote server.

This command securely terminates your session by invalidating the active authentication token. It ensures that no further authenticated operations can be performed until you log in again.

Terminal Output

% ppl logout -h

Usage:
  ppl logout [flags]

Flags:
  -h, --help   Show help for the logout command

Note:
  Logging out only affects the current CLI context. Any automation scripts or background services
  using the same credentials must re-authenticate after logout.

logsCOMMON COMMAND

Display Logs

Fetch and display logs from a running container.

This command retrieves the standard output and error streams from a specified container, including logs from the main process and any background services.

Supports time-based filtering to isolate relevant logs.

Time Filtering Options:

--since Show logs generated after a specific time
--until Show logs generated before a specific time

Accepted Timestamp Formats:

RFC3339: 2013-01-02T13:23:37Z
Unix: 1672574400 (seconds since epoch)
Duration: 1h, 30m, 10s (relative to now)

Terminal Output

% ppl logs -h

Usage:
  ppl logs <container_id> [flags]

Aliases:
  logs, container logs

Flags:
  -h, --help             Show help for this command
  -s, --since string     Filter logs from this time onward
  -u, --until string     Filter logs up to this time

Examples:
  # View logs from the last hour
  ppl logs container123 --since 1h

  # View logs between two exact timestamps
  ppl logs container123 --since 2023-01-01T10:00:00Z --until 2023-01-01T12:00:00Z

  # Use Unix timestamp format
  ppl logs container123 --since 1672574400

pipelineMANAGEMENT COMMAND

Manage Pipelines

Administrative pipeline management for advanced lifecycle operations.

Provides control over pipeline administration, including redeployment, migration, ownership transfer, deletion, and advanced configuration. These operations affect pipeline availability, access, and visibility across users and teams.

Note: These actions may require administrative privileges depending on your role and workspace settings.

Terminal Output

% ppl pipeline -h

Usage:
  ppl pipeline [command]

Available Commands:
  list        List and browse pipelines available in your workspace

Flags:
  -h, --help  Show help for the pipeline command group

Examples:
  ppl pipeline list          # View all pipelines
  ppl pipeline --help        # Show available subcommands

Use "ppl pipeline [command] --help" for more information about a specific command.

pipelinesCOMMON COMMAND

List Pipelines

Display a list of all Pipelogic pipelines available to you.

This command shows metadata and configuration details for each pipeline, including:

Pipeline ID and name
Description and owner
Creation and last modified timestamps
Deployment status and activity history
Access permissions
Component dependencies and structure

Pipelines define the dataflow, logic, and execution behavior for your AI or data processing workloads.

Terminal Output

% ppl pipelines -h

Usage:
  ppl pipelines [flags]

Aliases:
  pipelines, pipeline list

Flags:
  -h, --help   Show help for this command

Examples:
  # View all accessible pipelines
  ppl pipelines

registerESSENTIAL COMMAND

Register Users

This command creates a registration request and submits it for administrator approval.
Once submitted:

The user will be added to the approval queue.
A confirmation email will be sent to the specified address.
The account will become active only after administrator approval.

⚠️ Registration does not automatically sign you in. After approval, use ppl login to access your account.

Terminal Output

% ppl register -h

Usage:
  ppl register [flags]

Flags:
      --email string         Email address for the new user account
      --first-name string    First (given) name of the user
      --last-name string     Last (family) name of the user
  -h, --help                 Show help for this command

releaseCOMMON COMMAND

Release Components

Build and publish a new version of the current component.

This command performs the following:

Compiles the component source code
Executes defined tests (if available)
Packages and releases the build to the Pipelogic platform
Attaches release notes or version metadata (optional)

Released components are versioned and immediately available for use in pipelines.

Log verbosity levels:

none – Suppress all logs
run – Show runtime logs only (default)
build – Show runtime and build logs
all – Show all logs (build, run, upload, etc.)

Terminal Output

% ppl release -h

Usage:
  ppl release [flags]

Flags:
  -h, --help               Show help for this command
  -m, --message string     Add release notes or a short description
  -d, --mode string        Specify the build mode (e.g., debug, release)
  -q, --quiet              Suppress all output logs (overrides verbosity)
  -v, --verbosity string   Set log verbosity (none|run|build|all) (default "run")

Examples:
  # Release a component with a message
  ppl release -m "Improved image pre-processing"

  # Release with full log output
  ppl release -v all

  # Release quietly
  ppl release --quiet

statsCOMMON COMMAND

Display Stats

Display detailed performance metrics and system statistics for a specific deployment.

This command provides real-time visibility into the behavior and resource utilization of your deployment. It is useful for monitoring, performance tuning, and debugging.

Metrics displayed include:

CPU and memory usage per container
I/O statistics and network throughput
Component-level performance breakdowns
Request and response rates, latencies, and error counts
Health status and lifecycle timing information

Terminal Output

% ppl stats -h

Usage:
  ppl stats <deployment_id> [flags]

Flags:
  -h, --help   Show help for the stats command

Examples:
  # View stats for a deployment by ID
  ppl stats 489d-bf13-f001-92f1

typeMANAGEMENT COMMAND

Manage Types

Define and manage custom data types for use in component interfaces and pipeline connections.

Types enable:

Strong typing for component inputs and outputs
Schema-based validation and enforcement
Interface compatibility and type safety across pipelines
Better documentation and reusability of complex data structures

Supported:

Built-in primitives (e.g., String, Int, Float, Bool)
Composite structures (e.g., Tuples, Maps, Lists)
Custom types with namespacing and versioning for cross-project use

Terminal Output

% ppl type -h

Usage:
  ppl type [command]

Available Commands:
  get         Retrieve the structure of a registered type
  add         Add a new type definition from a file or inline input
  push        Upload a locally defined type to the server
  list        List all available types in the current workspace

Flags:
  -h, --help  Show help for the type command group

Examples:
  ppl type get BoundingBox
  ppl type add my_custom_type.txt
  ppl type push my_type_name
  ppl type list

Use "ppl type [command] --help" for more information about a specific subcommand.

undeployCOMMON COMMAND

Undeploy Pipelines

Gracefully stop and remove a running pipeline deployment.

This command halts all active pipeline components, releases compute resources, and cleans up temporary files and artifacts. The deployment will be marked as stopped, but historical logs and monitoring data will remain available.

Use the --save flag to retain any generated outputs and artifacts prior to cleanup — useful for debugging and post-analysis.

Terminal Output

% ppl undeploy -h

Usage:
  ppl undeploy <deployment_id> [flags]

Aliases:
  undeploy, pipeline undeploy

Flags:
  -s, --save   Preserve generated files and artifacts before cleanup
  -h, --help   Show help for this command

Examples:
  # Stop a running deployment
  ppl undeploy dpl-1234

  # Save outputs before undeploying
  ppl undeploy dpl-1234 --save

upgradeESSENTIAL COMMAND

Upgrade the CLI

Upgrade the PPL CLI to the latest available version.

This command:

Checks for the latest version on the server
Downloads the appropriate binary for your OS and architecture
Atomically replaces the current CLI executable
Preserves existing configuration and credentials

Supported platforms:

Linux: amd64, arm64
macOS: amd64, arm64

The upgrade process is safe and atomic—if an error occurs during download or installation, your current CLI will remain intact.

Use --force to re-download and reinstall the CLI, even if you're already running the latest version.

Terminal Output

% ppl upgrade -h

Usage:
  ppl upgrade [flags]

Flags:
  -f, --force   Force reinstallation of the current/latest version
  -h, --help    Show help for this command

versionESSENTIAL COMMAND

Version

Display the current installed version of the Pipelogic CLI.

This command is useful for:

Verifying your local CLI installation
Ensuring compatibility with the Pipelogic platform
Providing version details in support tickets
Determining if an upgrade is necessary

To update to the latest version, use: ppl upgrade

Terminal Output

% ppl version -h

Usage:
  ppl version [flags]

Flags:
  -h, --help   Show help for this command