### CLI Start Method Example

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Illustrates how the `start` method converts a user command like 'dip rails c' into ['run', 'rails', 'c'] before dispatching.

```ruby
# User runs: dip rails c
# start(['rails', 'c'])
# Converts to: ['run', 'rails', 'c'] before dispatching
```

--------------------------------

### Example: Start Service with Docker Compose

Source: https://github.com/bibendi/dip/blob/master/_autodocs/09-infra-and-ssh.md

Shows how to initialize and execute the `Up` command for a service, including passing custom Docker Compose arguments like '--no-color'. Illustrates the network creation and the final Docker Compose command executed.

```ruby
service = Service.new(:postgres, path: '~/infra/postgres')
Up.new('--no-color', service: service).execute
# Creates network: dip-net-postgres-latest
# Runs: docker compose up --detach --no-color
```

--------------------------------

### Example Kubectl Execution

Source: https://github.com/bibendi/dip/blob/master/_autodocs/08-runners.md

Demonstrates how to execute a Kubectl command to get pods within a specific namespace.

```ruby
Kubectl.new('get', 'pods').execute
# Runs: kubectl --namespace production get pods
```

--------------------------------

### Interaction Command Examples

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Examples demonstrating how to run various interaction commands, including Rails console, port publishing, and database migrations.

```shell
dip run rails c
dip run -p 3000:3000 bundle exec puma
dip run rake db:migrate
```

--------------------------------

### Dip Provisioning Steps

Source: https://github.com/bibendi/dip/blob/master/README.md

Defines a sequence of commands to be executed during the provisioning process, including stopping containers, cleaning cache, starting services, and running setup scripts.

```yaml
provision:
  - dip compose down --volumes
  - dip clean_cache
  - dip compose up -d pg redis
  - dip bash -c ./bin/setup
```

--------------------------------

### Kubernetes Command Examples

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Examples of using the 'dip ktl' command to interact with Kubernetes resources.

```shell
dip ktl get pods
dip ktl get svc
```

--------------------------------

### Start Infrastructure Services

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Use `dip infra up` to start infrastructure services. By default, it pulls updates before starting. Use `-n` to specify services or pass additional Docker Compose arguments.

```bash
dip infra up
```

```bash
dip infra up -n service1
```

```bash
dip infra up --update=false
```

```bash
dip infra up service1 --build
```

--------------------------------

### Start Infrastructure Services

Source: https://github.com/bibendi/dip/blob/master/_autodocs/00-index.md

Initiate infrastructure services like PostgreSQL using Dip.

```ruby
service = Dip::Commands::Infra::Service.new(:postgres, git: '...')
Dip::Commands::Infra::Up.new(service: service).execute
```

--------------------------------

### Accessing ConfigKeyMissingError Example

Source: https://github.com/bibendi/dip/blob/master/_autodocs/03-configuration.md

Example demonstrating when ConfigKeyMissingError is raised.

```ruby
config.kubectl  # Raises ConfigKeyMissingError if kubectl section not in dip.yml
```

--------------------------------

### CLI Start Method

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

The entry point for the CLI. It parses command-line arguments and routes them to the correct command handler.

```ruby
CLI.start(argv)
```

--------------------------------

### Dip Infrastructure Service Configuration Example

Source: https://github.com/bibendi/dip/blob/master/_autodocs/09-infra-and-ssh.md

Example YAML configuration for defining infrastructure services like PostgreSQL, Kafka, and Redis. Services can be specified by Git repository and reference, or by a local path.

```yaml
# dip.yml
infra:
  postgres:
    git: https://github.com/bibendi/dip-postgres.git
    ref: v1.0
  
  kafka:
    path: ~/shared-infrastructure/kafka

  redis:
    git: https://github.com/bibendi/dip-redis.git
    # ref defaults to 'latest'
```

--------------------------------

### Docker Compose Command Examples

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Examples of using the 'dip compose' command for various Docker Compose operations.

```shell
dip compose up -d
dip compose down
dip compose logs rails
```

--------------------------------

### CLI Entry Point

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

The `start` method is the main entry point for the CLI. It parses command-line arguments and dispatches them to the appropriate command handler.

```APIDOC
## CLI.start(argv)

### Description
Entry point for the CLI. Parses argv and dispatches to appropriate command handler.

### Method
`CLI.start(argv)`

### Parameters
#### Path Parameters
- **argv** (Array) - Command line arguments

### Processing Steps:
1. Extracts runtime variables from argv using `RunVars.call`
2. If argv first element is not a top-level command and exists as an interaction command, inserts "run"
3. Calls Thor's start with processed argv

### Example:
```ruby
# User runs: dip rails c
# start(['rails', 'c'])
# Converts to: ['run', 'rails', 'c'] before dispatching
```
```

--------------------------------

### Example Output for 'dip ls'

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Shows the expected formatted output when listing available commands.

```text
bash     # Open the Bash shell in app's container
rails    # Run Rails command
rails s  # Run Rails server at http://localhost:3000
```

--------------------------------

### Infrastructure Config Example

Source: https://github.com/bibendi/dip/blob/master/_autodocs/10-types-and-errors.md

Specifies infrastructure details, requiring either a git repository or a local path.

```yaml
infra:
  postgres:
    git: https://github.com/bibendi/dip-postgres.git
    ref: v1.0
  redis:
    path: ~/infrastructure/redis
```

--------------------------------

### Kubernetes Config Example

Source: https://github.com/bibendi/dip/blob/master/_autodocs/10-types-and-errors.md

Defines the Kubernetes namespace for deployment.

```yaml
kubectl:
  namespace: production
```

--------------------------------

### Example: Get Current User ID

Source: https://github.com/bibendi/dip/blob/master/_autodocs/04-environment.md

Shows an example of the integer UID returned by `find_current_user` for a typical non-root user.

```ruby
find_current_user  # => 1000 (typical non-root user)
```

--------------------------------

### Start Docker Services

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Runs the 'docker compose up' command for specified services. Delegates to the 'compose' method.

```ruby
up(*argv) -> void
```

--------------------------------

### Basic Dip Configuration Example

Source: https://github.com/bibendi/dip/blob/master/README.md

This is a minimal `dip.yml` configuration defining version, environment variables, compose files, project name, and kubectl namespace.

```yaml
version: '8.0'

environment:
  COMPOSE_EXT: development
  STAGE: "staging"

compose:
  files:
    - docker/docker-compose.yml
    - docker/docker-compose.$COMPOSE_EXT.yml
    - docker/docker-compose.$DIP_OS.yml
  project_name: bear

kubectl:
  namespace: rocket-$STAGE
```

--------------------------------

### Start SSH Agent with Dip

Source: https://github.com/bibendi/dip/blob/master/_autodocs/11-integration-guide.md

Starts an SSH agent using Dip, specifying the key file, volume, and interactive mode. Ensure the SSH key and volume path are correctly set.

```ruby
require 'dip'
require 'dip/commands/ssh'

Dip::Commands::SSH::Up.new(
  key: "#{ENV['HOME']}/.ssh/id_rsa",
  volume: ENV['HOME'],
  interactive: true
).execute
```

--------------------------------

### Dip::Commands::Infra::Up

Source: https://github.com/bibendi/dip/blob/master/_autodocs/09-infra-and-ssh.md

Starts infrastructure services using Docker Compose. It handles network creation and service environment variables.

```APIDOC
## Dip::Commands::Infra::Up

### Description
Starts infrastructure services using Docker Compose. This command ensures the necessary Docker network is created and runs the service with its defined environment variables.

### Method
Initialize with `Up.new(*compose_argv, service:)` and then call `execute`.

### Parameters
#### Initialize Parameters
- **\*compose_argv** (Array) - Optional - Additional Docker Compose arguments.
- **service** (Service) - Required - Service instance to start.

### Execute
#### Method
`execute -> void`

#### Description
Starts the infrastructure service. This involves changing to the service directory, creating a Docker network if it doesn't exist, and running `docker compose up --detach`.

#### Execution Steps
1. Changes to service directory.
2. Creates Docker network: `docker network create {network_name}`.
3. Runs `docker compose up --detach` with:
   - Service environment variables.
   - Additional compose arguments.
4. Ignores "network already exists" error.

### Example
```ruby
service = Service.new(:postgres, path: '~/infra/postgres')
Up.new('--no-color', service: service).execute
```
```

--------------------------------

### KubectlRunner kubectl_arguments format example

Source: https://github.com/bibendi/dip/blob/master/_autodocs/08-runners.md

This example shows the expected format of the Array returned by the kubectl_arguments method, detailing the structure of kubectl exec arguments.

```ruby
[
  'exec',
  '--tty',
  '--stdin',
  [--container CONTAINER,]  # If container specified in pod
  POD,
  '--',
  [ENTRYPOINT,]             # If defined
  COMMAND,
  ...user_args
]
```

--------------------------------

### KubectlRunner pod parsing example

Source: https://github.com/bibendi/dip/blob/master/_autodocs/08-runners.md

This example demonstrates how the pod field is parsed in KubectlRunner, showing the conversion of a service/container format to pod and container values.

```ruby
command[:pod] = 'svc/app:app-container'
# Parsed as: pod='svc/app', container='app-container'

command[:entrypoint] = '/bin/sh'
# Arguments: [..., '--container', 'app-container', 'svc/app', '--', '/bin/sh', ...]
```

--------------------------------

### Interaction Entry Example

Source: https://github.com/bibendi/dip/blob/master/_autodocs/10-types-and-errors.md

Defines how to interact with a service, including commands, environment variables, and subcommands.

```yaml
interaction:
  rails:
    description: Run Rails commands
    service: app
    command: bundle exec rails
    shell: true
    default_args: ''
    environment:
      RAILS_ENV: development
    compose:
      method: run
      profiles: []
      run_options: [no-deps]
    subcommands:
      s:
        description: Run Rails server
        service: web
        compose:
          run_options: [service-ports, use-aliases]
```

--------------------------------

### Example: Update Service from Git

Source: https://github.com/bibendi/dip/blob/master/_autodocs/09-infra-and-ssh.md

Demonstrates how to create a `Service` object and then use the `Update` command to clone or pull changes from its git repository. Shows expected behavior for first-time clones versus subsequent updates.

```ruby
service = Service.new(:postgres, git: 'https://github.com/bibendi/dip-postgres.git', ref: 'v1.0')
Update.new(service: service).execute
# First run: git clone ...
# Subsequent runs: git pull --rebase
```

--------------------------------

### Using Infrastructure Services with Dip

Source: https://github.com/bibendi/dip/blob/master/_autodocs/09-infra-and-ssh.md

Ruby code demonstrating how to load infrastructure service configurations, create service instances, and manage their lifecycle (update, start, stop) using Dip commands.

```ruby
require 'dip'

# Get service from config
services = Dip.config.infra
postgres_config = services[:postgres]

# Create service instance
service = Dip::Commands::Infra::Service.new(:postgres, **postgres_config)

# Update from git
Dip::Commands::Infra::Update.new(service: service).execute

# Start service
Dip::Commands::Infra::Up.new(service: service).execute

# Stop service
Dip::Commands::Infra::Down.new(service: service).execute
```

--------------------------------

### Config.new

Source: https://github.com/bibendi/dip/blob/master/_autodocs/03-configuration.md

Creates a new Config instance. This instance will search for `dip.yml` starting from the specified working directory.

```APIDOC
## Config.new(work_dir)

### Description
Creates a new Config instance that will search for `dip.yml` starting from `work_dir`.

### Method
Class Method

### Parameters
#### Path Parameters
- **work_dir** (String, Pathname) - Optional - Working directory to start search from. Defaults to `Dir.pwd`.

### Returns
A new `Dip::Config` instance.

### Example
```ruby
config = Dip::Config.new('/path/to/project')
```
```

--------------------------------

### Initialize Dip Infra Up Command

Source: https://github.com/bibendi/dip/blob/master/_autodocs/09-infra-and-ssh.md

Initializes the `Up` command for starting infrastructure services. It accepts additional Docker Compose arguments and the service instance to be started.

```ruby
Up.new(*compose_argv, service:) -> Dip::Commands::Infra::Up
```

--------------------------------

### Manage Infrastructure Services (Update, Up, Down)

Source: https://github.com/bibendi/dip/blob/master/_autodocs/11-integration-guide.md

This snippet demonstrates how to manage infrastructure services. It includes loading service configuration, updating from a repository, starting, and stopping the service.

```ruby
require 'dip'
require 'dip/commands/infra/service'
require 'dip/commands/infra'

# Load service from config
config = Dip.config
postgres_params = config.infra[:postgres]
service = Dip::Commands::Infra::Service.new(:postgres, **postgres_params)

# Update from repository
Dip::Commands::Infra::Update.new(service: service).execute

# Start service
Dip::Commands::Infra::Up.new(service: service).execute

# Stop service
Dip::Commands::Infra::Down.new(service: service).execute
```

--------------------------------

### Initialize ConfigFinder

Source: https://github.com/bibendi/dip/blob/master/_autodocs/03-configuration.md

Creates a finder that searches for `dip.yml` or `dip.override.yml` starting from the specified working directory. Set `override: true` to prioritize `dip.override.yml`.

```ruby
ConfigFinder.new(work_dir, override: false) -> ConfigFinder
```

--------------------------------

### Up Command

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Runs the `docker compose up` command to create and start services defined in the Docker Compose configuration.

```APIDOC
## up(*argv)

### Description
Runs `docker compose up` command.

### Method
`up(*argv)`

### Endpoint
`dip up [OPTIONS] SERVICE`

### Parameters
#### Path Parameters
- **argv** (Array) - Up options and service names

### Delegates to:
`compose("up", *argv)`
```

--------------------------------

### Initialize Dip Configuration

Source: https://github.com/bibendi/dip/blob/master/_autodocs/03-configuration.md

Creates a new Dip::Config instance. The instance searches for 'dip.yml' starting from the specified working directory.

```Ruby
Config.new(work_dir = Dir.pwd) -> Dip::Config
```

--------------------------------

### Install Dip Gem

Source: https://github.com/bibendi/dip/blob/master/README.md

Install the Dip gem using the RubyGems package manager.

```sh
gem install dip
```

--------------------------------

### LocalRunner execute method example

Source: https://github.com/bibendi/dip/blob/master/_autodocs/08-runners.md

This example illustrates how the execute method in LocalRunner runs a command locally. It shows that the current Ruby process is replaced by the executed command.

```ruby
# If command is 'make' and argv is ['build']
execute
# Runs: make build

# The current Ruby process is replaced
```

--------------------------------

### Run dip commands for Dockerized development

Source: https://github.com/bibendi/dip/blob/master/AGENTS.md

Use these commands for development within Docker. The 'dip provision' command is for initial setup.

```sh
# Dev inside Docker (preferred — most commands require docker-compose)
dip provision          # first-time setup: copies lefthook config, cleans Gemfile.lock, installs deps
dip rspec              # run tests
dip rspec spec/path    # single file
dip rubocop            # lint
dip rubocop -a         # lint + auto-correct
dip pry                # open Pry console
dip bundle install     # add dependencies
```

--------------------------------

### Compose Config Example

Source: https://github.com/bibendi/dip/blob/master/_autodocs/10-types-and-errors.md

Specifies configuration for Docker Compose, including files, project name, and command execution method.

```yaml
compose:
  files:
    - docker-compose.yml
    - docker-compose.$ENVIRONMENT.yml
  project_name: myapp-dev
  project_directory: .
  command: docker-compose  # custom override
```

--------------------------------

### Complex Subcommand Structure Example

Source: https://github.com/bibendi/dip/blob/master/_autodocs/06-interaction-tree.md

Demonstrates how to define and interact with a complex, nested subcommand structure using the Interaction Tree. This example shows a 'k' command with 'bash' and 'rails' subcommands, where 'rails' itself has a 'c' subcommand.

```yaml
# dip.yml
interaction:
  k:
    description: Run Kubernetes commands
    pod: svc/app:app-container
    command: /bin/bash
    subcommands:
      bash:
        description: Get a shell
        command: /bin/bash
      rails:
        description: Run Rails
        command: bundle exec rails
        subcommands:
          c:
            description: Rails console
            command: bundle exec rails c
```

```ruby
tree = Dip::InteractionTree.new(interactions)

# All three commands are available:
tree.find('k')          # => executes /bin/bash
tree.find('k', 'bash')  # => executes /bin/bash (subcommand)
tree.find('k', 'rails') # => executes bundle exec rails
tree.find('k', 'rails', 'c')  # => executes bundle exec rails c

# List shows all:
tree.list.keys
# => ['k', 'k bash', 'k rails', 'k rails c']
```

--------------------------------

### Environment Hash Example

Source: https://github.com/bibendi/dip/blob/master/_autodocs/10-types-and-errors.md

Maps environment variable names to values. Supports interpolation with $VAR references.

```yaml
environment:
  RAILS_ENV: development
  APP_NAME: myapp-$ENVIRONMENT
  DEBUG: 'false'
```

--------------------------------

### Integrate Dip with Shell

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Provides subcommands for shell integration. 'start' integrates Dip into the current shell by default, while 'inject' adds specific aliases.

```ruby
console -> Dip::CLI::Console
```

--------------------------------

### Start SSH Agent Container

Source: https://github.com/bibendi/dip/blob/master/README.md

Starts an SSH agent container using the 'dip ssh up' command. This is useful for forwarding your local SSH keys to a containerized environment. Ensure your docker-compose.yml is configured to use the 'ssh_data' volume and the SSH_AUTH_SOCK environment variable.

```sh
dip ssh up
```

--------------------------------

### Import Dip Library

Source: https://github.com/bibendi/dip/blob/master/_autodocs/11-integration-guide.md

Include the Dip library in your Ruby project to start using its functionalities.

```ruby
require 'dip'
```

--------------------------------

### Dip::Commands::SSH::Up

Source: https://github.com/bibendi/dip/blob/master/_autodocs/09-infra-and-ssh.md

Starts an SSH agent container and adds an SSH private key to it. It requires the path to the SSH key, a host volume, and an interactive flag.

```APIDOC
## Dip::Commands::SSH::Up

### Description
Starts SSH agent container and adds the SSH key.

### Method
`initialize(key:, volume:, interactive:, user: nil)`

### Parameters
#### Path Parameters
- **key** (String) - Required - Path to SSH private key
- **volume** (String) - Required - Host volume to mount
- **interactive** (Boolean) - Required - Run container in interactive mode
- **user** (String) - Optional - UID to run container as

### Method
`execute`

### Description
Starts the SSH agent container. This involves creating a Docker volume named `ssh_data`, starting the `whilp/ssh-agent` container in detached mode, and then adding the SSH key to the agent within this new container. The process uses mounted volumes for data persistence and SSH key access, and runs interactively with a TTY if enabled.

### Request Example
```ruby
SSH::Up.new(
  key: '$HOME/.ssh/id_rsa',
  volume: '$HOME',
  interactive: true,
  user: '1000'
).execute
```

### Response
#### Success Response (void)
Indicates the SSH agent container has been started and the key has been added.
```

--------------------------------

### Custom Tool for Database Migrations with Dip

Source: https://github.com/bibendi/dip/blob/master/_autodocs/11-integration-guide.md

An example of building a custom Dip-based tool for managing database migrations. It includes validation, running migrations, and rolling back changes.

```ruby
require 'dip'
require 'dip/commands/run'

class DatabaseMigration
  attr_reader :config, :env

  def initialize
    @config = Dip.config
    @env = Dip.env

    if !config.exist?
      raise "dip.yml not found"
    end
  end

  def validate
    config.validate
    puts "✓ Configuration valid"
  end

  def run_migrations(env_name = 'development')
    puts "Running migrations for #{env_name}..."
    
    env['RAILS_ENV'] = env_name
    
    begin
      Dip::Commands::Run.new('rake', 'db:migrate').execute
      puts "✓ Migrations completed"
    rescue Dip::Error => e
      puts "✗ Migration failed: #{e.message}"
      exit 1
    end
  end

  def rollback(steps = 1)
    puts "Rolling back #{steps} migrations..."
    
    begin
      Dip::Commands::Run.new('rake', "db:rollback[#{steps}]").execute
      puts "✓ Rollback completed"
    rescue Dip::Error => e
      puts "✗ Rollback failed: #{e.message}"
      exit 1
    end
  end
end

# Usage
tool = DatabaseMigration.new
tool.validate
tool.run_migrations('test')
tool.rollback(1)
```

--------------------------------

### Run Application Commands Directly

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Execute application commands like 'rails c' or 'bundle install' directly using 'dip'. This is a shortcut for 'dip run <command>'.

```shell
# Run command directly (without 'run' keyword)
dip rails c
dip bundle install
```

--------------------------------

### Interpolate Environment Variables

Source: https://github.com/bibendi/dip/blob/master/_autodocs/11-integration-guide.md

Interpolate a string using environment variables. Sets example variables and then interpolates a connection string.

```ruby
env = Dip.env
env['RAILS_ENV'] = 'production'
env['DB_PORT'] = '5432'

# Interpolate a string with variables
connection_string = env.interpolate('postgres://localhost:$DB_PORT/myapp')
# => 'postgres://localhost:5432/myapp'
```

--------------------------------

### Manage Infrastructure Services with Dip

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Offers subcommands for managing infrastructure services. Use 'update' to refresh services, 'up' to start them, and 'down' to stop them.

```ruby
infra -> Dip::CLI::Infra
```

--------------------------------

### Dip Console Start Command

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Integrates Dip commands into the current shell environment as aliases and functions. This command executes the Dip::Commands::Console::Start class.

```bash
dip console start
```

--------------------------------

### Using $DIP_CURRENT_USER Environment Variable

Source: https://github.com/bibendi/dip/blob/master/README.md

Example showing how to expose the current user ID (UID) to run containers with the same user as the host machine.

```yaml
# dip.yml (1)
environment:
  UID: ${DIP_CURRENT_USER}
```

```yaml
# docker-compose.yml (2)
services:
  app:
    image: ruby
    user: ${UID:-1000}
```

--------------------------------

### Example: Find Relative Path

Source: https://github.com/bibendi/dip/blob/master/_autodocs/04-environment.md

Demonstrates how `find_work_dir_rel_path` returns the relative path to the `dip.yml` directory. Assumes `dip.yml` is in the project root and the current working directory is a subdirectory.

```ruby
# If cwd is /project/sub/app and dip.yml is in /project:
find_work_dir_rel_path  # => 'sub/app'
```

--------------------------------

### Using $DIP_WORK_DIR_REL_PATH Environment Variable

Source: https://github.com/bibendi/dip/blob/master/README.md

Example demonstrating how to use the relative path to the Dip config directory in environment variables for mounting local directories into containers.

```yaml
# dip.yml (1)
environment:
  WORK_DIR: /app/${DIP_WORK_DIR_REL_PATH}
```

```yaml
# docker-compose.yml (2)
services:
  app:
    working_dir: ${WORK_DIR:-/app}
```

--------------------------------

### Get Dip Executable Path

Source: https://github.com/bibendi/dip/blob/master/_autodocs/02-global-api.md

Returns the path to the `dip` executable. If the program name starts with `./`, returns the expanded absolute path; otherwise, returns `"dip"`.

```ruby
Dip.bin_path  # => "dip" or "/usr/local/bin/dip"
```

--------------------------------

### Managing Kubernetes Resources with Dip

Source: https://github.com/bibendi/dip/blob/master/_autodocs/00-index.md

Interact with Kubernetes using Dip's Kubectl command interface. Execute commands like 'get pods' and 'logs'.

```ruby
require 'dip/commands/kubectl'

Dip::Commands::Kubectl.new('get', 'pods').execute
Dip::Commands::Kubectl.new('logs', '-f', 'pod-name').execute
```

--------------------------------

### Managing Infrastructure Services with Dip

Source: https://github.com/bibendi/dip/blob/master/_autodocs/00-index.md

Control infrastructure services (e.g., databases) using Dip's Infra commands. Includes creating, updating, starting, and stopping services.

```ruby
require 'dip/commands/infra'
require 'dip/commands/infra/service'

service = Dip::Commands::Infra::Service.new(:postgres, git: 'https://...')
Dip::Commands::Infra::Update.new(service: service).execute
Dip::Commands::Infra::Up.new(service: service).execute
Dip::Commands::Infra::Down.new(service: service).execute
```

--------------------------------

### Start SSH Agent Container

Source: https://github.com/bibendi/dip/blob/master/_autodocs/09-infra-and-ssh.md

Initiates an SSH agent container using the 'whilp/ssh-agent' image. This is useful for managing SSH keys securely within a containerized environment. Ensure the specified key path and volume are accessible.

```ruby
SSH::Up.new(
  key: '$HOME/.ssh/id_rsa',
  volume: '$HOME',
  interactive: true,
  user: '1000'
).execute
# Creates ssh_data volume
# Starts: docker run -u 1000 --detach --volume ssh_data:/ssh --name=ssh-agent whilp/ssh-agent
# Adds key: docker run --rm --volume ssh_data:/ssh --volume $HOME:$HOME --interactive --tty whilp/ssh-agent ssh-add ~/.ssh/id_rsa
```

--------------------------------

### Accessing Configuration Sections

Source: https://github.com/bibendi/dip/blob/master/_autodocs/03-configuration.md

Demonstrates how to access various configuration sections like Docker Compose, Kubernetes, and interaction commands.

```ruby
config = Dip.config

# Docker Compose settings
compose_files = config.compose[:files]     # => ['docker-compose.yml']
compose_project = config.compose[:project_name]  # => 'myapp'

# Kubernetes settings
k8s_namespace = config.kubectl[:namespace]  # => 'production'

# Interaction commands
rails_cmd = config.interaction[:rails]     # => { service: 'app', command: '...' }

# Provisioning and preflight
config.provision.each { |cmd| system(cmd) }
config.preflight.each { |cmd| system(cmd) }
```

--------------------------------

### Example Interaction Definition

Source: https://github.com/bibendi/dip/blob/master/_autodocs/06-interaction-tree.md

This YAML defines a 'rails' interaction with a subcommand 's' for running the Rails server. It demonstrates how to specify service, command, and composition options for interactions.

```yaml
interaction:
  rails:
    description: Run Rails commands
    service: app
    command: bundle exec rails
    subcommands:
      s:
        description: Run Rails server
        service: web
        compose:
          run_options: [service-ports, use-aliases]

```

--------------------------------

### Use Commands Without 'dip' Prefix After Integration

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Once shell integration is active, you can run commands like 'bundle install', 'rails c', and 'compose logs' directly.

```shell
# Now use commands without 'dip' prefix
bundle install
rails c
compose logs
```

--------------------------------

### Dip.bin_path

Source: https://github.com/bibendi/dip/blob/master/_autodocs/02-global-api.md

Returns the path to the `dip` executable. If the program name starts with `./`, returns the expanded absolute path. Otherwise, returns the string `"dip"`.

```APIDOC
## Dip.bin_path

### Description
Returns the path to the `dip` executable. If the program name starts with `./`, returns the expanded absolute path. Otherwise, returns the string `"dip"`.

### Returns
String path to the dip binary

### Example
```ruby
Dip.bin_path  # => "dip" or "/usr/local/bin/dip"
```
```

--------------------------------

### Format Published Ports for Docker Compose

Source: https://github.com/bibendi/dip/blob/master/_autodocs/08-runners.md

Formats published ports from command options into Docker Compose '--publish=port:port' flags. Example shows formatting for multiple ports.

```ruby
# With options[:publish] = ['3000:3000', '8000:8000']
published_ports  # => ['--publish=3000:3000', '--publish=8000:8000']
```

--------------------------------

### Start SSH Agent Container with Specific UID

Source: https://github.com/bibendi/dip/blob/master/README.md

Starts an SSH agent container and specifies a user ID (UID) for non-root user execution. This is particularly useful when your application in docker-compose.yml is configured to run as a specific user.

```sh
dip ssh up -u 1000
```

--------------------------------

### Build and List Commands from Interaction Tree

Source: https://github.com/bibendi/dip/blob/master/_autodocs/11-integration-guide.md

Initializes an `InteractionTree` from Dip configuration and lists all available commands with their descriptions. Use this to discover available commands.

```ruby
require 'dip'

config = Dip.config
tree = Dip::InteractionTree.new(config.interaction)

# List all commands
tree.list.each do |name, definition|
  description = definition[:description] || 'No description'
  puts "#{name}: #{description}"
end
```

--------------------------------

### Dip::Environment.initialize

Source: https://github.com/bibendi/dip/blob/master/_autodocs/04-environment.md

Creates a new Environment instance, loading default variables and merging them with the host environment. Variables are interpolated during this process.

```APIDOC
## initialize(default_vars)

Creates a new Environment instance with default variables loaded.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| default_vars | Hash | Environment variables from config (key/value pairs) |

### Notes:
- Variables in `default_vars` are merged with existing ENV, with ENV taking precedence
- Variables are interpolated during merge using `interpolate`

### Example:

```ruby
env = Dip::Environment.new({ RAILS_ENV: 'development', APP_PORT: '3000' })
```
```

--------------------------------

### Catch Generic Dip Error

Source: https://github.com/bibendi/dip/blob/master/_autodocs/10-types-and-errors.md

Example of how to catch any Dip-specific error during configuration validation.

```Ruby
begin
  Dip.config.validate
rescue Dip::Error => e
  puts "Error: #{e.message}"
end
```

--------------------------------

### Manage Docker Compose Services

Source: https://github.com/bibendi/dip/blob/master/_autodocs/00-index.md

Control Docker Compose services, such as starting and stopping them.

```ruby
Dip::Commands::Compose.new('up', '-d').execute
Dip::Commands::Compose.new('down').execute
```

--------------------------------

### Initialize Infrastructure Service from Git

Source: https://github.com/bibendi/dip/blob/master/_autodocs/09-infra-and-ssh.md

Create a new infrastructure service instance by specifying a Git repository URL and a reference (branch or tag). The service location will be determined based on the Git repository and ref.

```ruby
service = Service.new(
  :postgres,
  git: 'https://github.com/bibendi/dip-postgres.git',
  ref: 'v1.0'
)
```

--------------------------------

### Initialize Infrastructure Service from Local Path

Source: https://github.com/bibendi/dip/blob/master/_autodocs/09-infra-and-ssh.md

Create a new infrastructure service instance by providing a local path to the service directory. This is useful for services managed directly on the local filesystem.

```ruby
service = Service.new(
  :kafka,
  path: '~/infrastructure/kafka'
)
```

--------------------------------

### Run Dip Provision Commands

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Executes all commands defined in the 'provision' section of the dip.yml configuration file. Use this to set up project dependencies or environments.

```ruby
provision -> void
```

--------------------------------

### Manage Infrastructure

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Bring infrastructure components like Kafka up or down using 'dip infra'.

```shell
# Infrastructure
dip infra up
dip infra down -n kafka
```

--------------------------------

### Service.new

Source: https://github.com/bibendi/dip/blob/master/_autodocs/09-infra-and-ssh.md

Creates a new infrastructure service instance. It can be initialized either from a Git repository or a local path. Validation ensures that at least one of `git` or `path` is provided.

```APIDOC
## Service.new

### Description
Creates a new infrastructure service instance.

### Method
`Service.new(name, git: nil, ref: nil, path: nil)`

### Parameters
#### Path Parameters
- **name** (String, Symbol) - Required - Service name
- **git** (String) - Optional - Git repository URL
- **ref** (String) - Optional - Git reference (branch/tag) to clone
- **path** (String) - Optional - Local path to service directory

### Request Example
```ruby
# From git repository
service = Service.new(
  :postgres,
  git: 'https://github.com/bibendi/dip-postgres.git',
  ref: 'v1.0'
)

# From local path
service = Service.new(
  :kafka,
  path: '~/infrastructure/kafka'
)
```
```

--------------------------------

### Get Config File Path

Source: https://github.com/bibendi/dip/blob/master/_autodocs/03-configuration.md

Returns the `Pathname` to the found configuration file, or `nil` if no file was found.

```ruby
finder.file_path -> Pathname, nil
```

--------------------------------

### Basic Configuration Loading

Source: https://github.com/bibendi/dip/blob/master/_autodocs/03-configuration.md

Loads the Dip configuration and checks if a configuration file exists. Validates the configuration if found.

```ruby
require 'dip'

config = Dip.config

if config.exist?
  puts "Using config: #{config.file_path}"
  config.validate
else
  puts "No dip.yml found"
end
```

--------------------------------

### Accessing Dip Configuration Properties

Source: https://github.com/bibendi/dip/blob/master/_autodocs/02-global-api.md

Demonstrates accessing various configuration properties like existence, file path, interaction commands, Docker Compose settings, Kubernetes settings, environment variables, provision commands, preflight commands, and infrastructure services.

```ruby
require 'dip'

config = Dip.config
config.exist?           # => true if dip.yml exists
config.file_path        # => Pathname to the config file
config.interaction      # => Hash of interaction commands
config.compose          # => Hash of Docker Compose config
config.kubectl          # => Hash of Kubernetes config
config.environment      # => Hash of env vars defined in config
config.provision        # => Array of provision commands
config.preflight        # => Array of preflight commands
config.infra            # => Hash of infrastructure services
```

--------------------------------

### Get Modules Directory Path

Source: https://github.com/bibendi/dip/blob/master/_autodocs/03-configuration.md

Returns the `Pathname` to the `.dip/` directory located alongside the found configuration file.

```ruby
finder.modules_dir -> Pathname
```

--------------------------------

### Define Version Mismatch Error Class

Source: https://github.com/bibendi/dip/blob/master/_autodocs/10-types-and-errors.md

Custom error class raised when the installed Dip version is insufficient for the configuration.

```Ruby
class VersionMismatchError < Dip::Error
end
```

--------------------------------

### Perform Kubernetes Operations

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Interact with your Kubernetes cluster using 'dip ktl' commands to get pods or view logs.

```shell
# Kubernetes operations
dip ktl get pods
dip ktl logs pod-name
```

--------------------------------

### List Available Commands

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Use 'dip ls' to see all available commands provided by the 'dip' tool.

```shell
# List available commands
dip ls
```

--------------------------------

### Get Current User ID

Source: https://github.com/bibendi/dip/blob/master/_autodocs/04-environment.md

Returns the User ID (UID) of the current process. This is typically a non-root user ID.

```ruby
find_current_user -> Integer
```

--------------------------------

### Get Dip Environment Object

Source: https://github.com/bibendi/dip/blob/master/_autodocs/02-global-api.md

Retrieves the singleton Dip environment object, initialized with configuration. Supports variable interpolation.

```ruby
env = Dip.env
env['APP_NAME']  # => interpolated value
```

--------------------------------

### Get Dip Configuration Object

Source: https://github.com/bibendi/dip/blob/master/_autodocs/02-global-api.md

Retrieves the singleton Dip configuration object. Configuration is loaded lazily from `dip.yml` and cached.

```ruby
config = Dip.config
```

--------------------------------

### Handle Dip Version Mismatches

Source: https://github.com/bibendi/dip/blob/master/_autodocs/11-integration-guide.md

Catch `Dip::VersionMismatchError` to inform users when their Dip version is incompatible. This guides them to upgrade.

```ruby
begin
  config = Dip.config
rescue Dip::VersionMismatchError => e
  puts "Please upgrade Dip: #{e.message}"
  exit 1
end
```

--------------------------------

### Loading Module Configurations

Source: https://github.com/bibendi/dip/blob/master/_autodocs/03-configuration.md

Explains how Dip loads module configurations from specified files when modules are defined in dip.yml.

```ruby
config = Dip.config

# With modules defined in dip.yml:
# modules:
#   - rails
#   - testing

# Module files are loaded from:
# - .dip/rails.yml
# - .dip/testing.yml

# The merged config includes all interaction commands from all modules
```

--------------------------------

### Dip Interaction Subcommand: Kubernetes Bash Shell

Source: https://github.com/bibendi/dip/blob/master/README.md

Configures a subcommand for the 'k' interaction to get a shell to a running Kubernetes container.

```yaml
    subcommands:
      bash:
        description: Get a shell to the running container
        command: /bin/bash
```

--------------------------------

### List Available Run Commands

Source: https://github.com/bibendi/dip/blob/master/README.md

Display all commands that can be executed using 'dip run', along with their descriptions.

```sh
dip ls

bash     # Open the Bash shell in app's container
rails    # Run Rails command
rails s  # Run Rails server at http://localhost:3000
```

--------------------------------

### Dip::Commands::Runners::Base#initialize

Source: https://github.com/bibendi/dip/blob/master/_autodocs/08-runners.md

Creates a new runner instance for executing commands. It accepts the command definition, user arguments, and additional options.

```APIDOC
## Dip::Commands::Runners::Base#initialize

### Description
Creates a new runner instance. It accepts the command definition, user arguments, and additional options.

### Method
`Base.new(command, argv, **options)`

### Parameters
#### Parameters
- **command** (Hash) - Expanded command definition from InteractionTree
- **argv** (Array) - Command arguments passed by user
- **options** (Hash) - Additional options (e.g., publish ports)

### Notes
- The `command` parameter contains all fields from the expanded command definition
- The `argv` parameter contains unconsumed arguments from the command line
```

--------------------------------

### Check Infrastructure Service Configuration

Source: https://github.com/bibendi/dip/blob/master/_autodocs/11-integration-guide.md

Iterate through the configured infrastructure services and print their details such as Git repository, path, and reference.

```ruby
require 'dip'

config = Dip.config

config.infra.each do |name, params|
  puts "Service: #{name}"
  puts "  Git: #{params[:git]}"
  puts "  Path: #{params[:path]}"
  puts "  Ref: #{params[:ref]}"
end
```

--------------------------------

### RunVars.initialize

Source: https://github.com/bibendi/dip/blob/master/_autodocs/05-command-execution.md

Initializes a new RunVars instance with command line arguments and an environment hash.

```APIDOC
## RunVars.initialize

### Description
Creates a new RunVars instance.

### Method
Instance Method

### Signature
`RunVars.new(argv, env = ENV) -> Dip::RunVars`

### Parameters
#### Parameters
- **argv** (Array) - Required - Command line arguments
- **env** (Hash) - Optional - Environment hash (default: ENV)
```

--------------------------------

### Building and Finding Commands in an Interaction Tree

Source: https://github.com/bibendi/dip/blob/master/_autodocs/00-index.md

Construct an interaction tree from Dip configuration and query it to find available commands and their arguments.

```ruby
tree = Dip::InteractionTree.new(config.interaction)

all_commands = tree.list
# => { 'rails' => {...}, 'rails s' => {...}, ... }

result = tree.find('rails', 's')
# => { command: {...}, argv: [] }
```

--------------------------------

### Get Configuration File Path

Source: https://github.com/bibendi/dip/blob/master/_autodocs/03-configuration.md

Returns the Pathname object for the discovered 'dip.yml' file. Returns nil if no 'dip.yml' is found in the directory tree.

```Ruby
config.file_path -> Pathname
```

--------------------------------

### Get Operating System Name

Source: https://github.com/bibendi/dip/blob/master/_autodocs/04-environment.md

Retrieves the current operating system name (e.g., 'linux', 'darwin'). It uses `Gem::Platform.local.os` for this purpose.

```ruby
find_os -> String
```

--------------------------------

### execute

Source: https://github.com/bibendi/dip/blob/master/_autodocs/08-runners.md

Runs a command using Docker Compose. It collects compose profiles, builds the necessary arguments (including profiles, method, run options, ports, service name, and user arguments), and then executes the command via `Dip::Commands::Compose`.

```APIDOC
## execute

### Description
Runs the command via Docker Compose.

### Method
`execute`

### Returns
`void`

### Execution Steps:
1. Collects compose profiles (if defined)
2. Builds compose arguments including:
   - Profiles (--profile flags)
   - Docker Compose method (run or up)
   - Run options (--no-deps, --service-ports, etc.)
   - Published ports (-p/--publish flags)
   - Service name
   - Command string
   - User arguments
3. Runs Docker Compose via `Dip::Commands::Compose`

### Profiles Handling:
- When profiles are used, the compose method is changed to "up"
- Run options are cleared (they're incompatible with up)
```

--------------------------------

### Get Dip Home Directory Path

Source: https://github.com/bibendi/dip/blob/master/_autodocs/02-global-api.md

Returns the expanded absolute path to the Dip home directory. Defaults to `~/.dip` but can be overridden by `DIP_HOME`.

```ruby
Dip.home_path  # => "/home/user/.dip"
```

--------------------------------

### Accessing and Interpolating Environment Variables with Dip

Source: https://github.com/bibendi/dip/blob/master/_autodocs/02-global-api.md

Shows how to access environment variables using `Dip.env`, fetch values with defaults, and perform variable interpolation.

```ruby
env = Dip.env

# Direct access
env['RAILS_ENV']  # => value or nil

# Fetch with default
env.fetch('APP_NAME') { 'default' }  # => value or 'default'

# Interpolation with variable expansion
interpolated = env.interpolate('$DIP_OS runs on $RAILS_ENV')
```

--------------------------------

### Display Dip Help Information

Source: https://github.com/bibendi/dip/blob/master/README.md

Use this command to see the available subcommands and their help messages.

```sh
dip --help
dip SUBCOMMAND --help
```

--------------------------------

### Get Path to Module File

Source: https://github.com/bibendi/dip/blob/master/_autodocs/03-configuration.md

Constructs the Pathname for a module file located in the '.dip/' directory, which resides alongside 'dip.yml'. The file does not need to exist.

```Ruby
config.module_file(filename) -> Pathname
```

```Ruby
config.module_file('rails')  # => #<Pathname:project/root/.dip/rails.yml>
```

--------------------------------

### Initialize Base Runner

Source: https://github.com/bibendi/dip/blob/master/_autodocs/08-runners.md

Creates a new runner instance. The `command` parameter includes the expanded command definition, and `argv` contains user-provided arguments. Additional options like publishing ports can be passed.

```ruby
Base.new(command, argv, **options) -> Dip::Commands::Runners::Base
```

--------------------------------

### Safely Access Optional Configuration Sections

Source: https://github.com/bibendi/dip/blob/master/_autodocs/10-types-and-errors.md

Demonstrates safe access to potentially missing configuration sections using presence checks and default values.

```ruby
config = Dip.config

# Safe access with presence check
if config.interaction.any?
  puts "Commands available"
end

# Access with defaults
compose_files = config.compose&.[](:files) || []
kubectl_namespace = config.kubectl&.[](:namespace)
```

--------------------------------

### Basic Environment Variable Access

Source: https://github.com/bibendi/dip/blob/master/_autodocs/04-environment.md

Demonstrates direct access to environment variables using hash-like syntax and safe fetching with a default value using the `fetch` method.

```ruby
env = Dip.env

# Direct access
env['RAILS_ENV']  # => 'development' or nil

# Fetch with default
env.fetch('PORT') { 3000 }  # => 3000 or set value
```

--------------------------------

### Pass Environment Variables in Shell Mode

Source: https://github.com/bibendi/dip/blob/master/README.md

Dip attempts to determine manually passed environment variables when in shell mode. Example shown with Rails migration.

```sh
VERSION=20180515103400 rails db:migrate:down
```

--------------------------------

### Initialize Dip::Commands::Compose

Source: https://github.com/bibendi/dip/blob/master/_autodocs/08-runners.md

Initializes the Compose command wrapper with Docker Compose arguments and an option to join them as a shell command.

```ruby
Compose.new(*argv, shell: true)
```

--------------------------------

### Dip Version Mismatch Error Message

Source: https://github.com/bibendi/dip/blob/master/_autodocs/01-overview.md

This is the format of the error message raised when the installed Dip version is lower than the minimum version required by the configuration file.

```text
Your dip version is `X.Y.Z`, but config requires minimum version `A.B.C`. Please upgrade your dip!
```

--------------------------------

### Get Docker Compose Profile Flags

Source: https://github.com/bibendi/dip/blob/master/_autodocs/08-runners.md

Retrieves Docker Compose profile flags. This method is private and returns an array of profile flags if profiles are defined.

```ruby
compose_profiles -> Array
```

--------------------------------

### Initialize Interaction Tree

Source: https://github.com/bibendi/dip/blob/master/_autodocs/06-interaction-tree.md

Initializes the Dip Interaction Tree by loading the configuration. This is the first step before interacting with commands.

```ruby
require 'dip'

config = Dip.config
tree = Dip::InteractionTree.new(config.interaction)
```

--------------------------------

### Inspect Dip Configuration

Source: https://github.com/bibendi/dip/blob/master/_autodocs/00-index.md

Pretty-print the entire Dip configuration to a hash for inspection.

```ruby
require 'dip'
require 'pp'

pp Dip.config.to_h
```

--------------------------------

### Initialize Environment with Default Variables

Source: https://github.com/bibendi/dip/blob/master/_autodocs/04-environment.md

Creates a new Dip::Environment instance. It merges provided default variables with existing environment variables, with existing ENV taking precedence. Variable interpolation is performed during this merge.

```ruby
env = Dip::Environment.new({ RAILS_ENV: 'development', APP_PORT: '3000' })
```

--------------------------------

### Manage Infrastructure Services

Source: https://github.com/bibendi/dip/blob/master/README.md

Commands to update, start, and stop shared infrastructure services managed by Dip. Services are pulled from specified Git repositories or local paths.

```sh
- `dip infra update` pulls updates from sources
- `dip infra up` starts all infra services
- `dip infra up -n kafka` starts a specific infra service
- `dip infra down` stops all infra services
- `dip infra down -n kafka` stops a specific infra service
```

--------------------------------

### Fetch Environment Variables with Defaults

Source: https://github.com/bibendi/dip/blob/master/_autodocs/11-integration-guide.md

Fetch environment variables, providing a default value if the variable is not set. Demonstrates fetching 'APP_PORT' and 'DEBUG'.

```ruby
env = Dip.env

port = env.fetch('APP_PORT') { '3000' }
debug = env.fetch('DEBUG') { 'false' }
```

--------------------------------

### Initialize Dip::Commands::Kubectl

Source: https://github.com/bibendi/dip/blob/master/_autodocs/08-runners.md

Initializes the Kubectl command wrapper with Kubectl arguments.

```ruby
Kubectl.new(*argv)
```

--------------------------------

### Get Environment Variables for Service

Source: https://github.com/bibendi/dip/blob/master/_autodocs/09-infra-and-ssh.md

Retrieve a hash of environment variables that should be passed to Docker Compose operations for the service. This includes compose project name and network name.

```ruby
service.env
# => {
#   'COMPOSE_PROJECT_NAME' => 'dip-infra-postgres-v1.0',
#   'DIP_INFRA_NETWORK_NAME' => 'dip-net-postgres-v1.0'
# }
```

--------------------------------

### Get Interpolated Environment Variables

Source: https://github.com/bibendi/dip/blob/master/_autodocs/04-environment.md

Retrieves a hash containing all interpolated environment variables managed by the Dip::Environment instance. The keys are strings and the values are interpolated strings.

```ruby
env.vars  # => { "RAILS_ENV" => "development", "DIP_OS" => "linux" }
```

--------------------------------

### Build Docker Services

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Runs the 'docker compose build' command for specified services. Delegates to the 'compose' method.

```ruby
build(*argv) -> void
```

--------------------------------

### Read Configuration Sections

Source: https://github.com/bibendi/dip/blob/master/_autodocs/11-integration-guide.md

Access various settings from the Dip configuration, including composed settings, Kubernetes details, custom commands, provisioning, and preflight checks.

```ruby
config = Dip.config

# Compose settings
files = config.compose[:files]
project = config.compose[:project_name]

# Kubernetes settings
namespace = config.kubectl[:namespace]

# Custom commands
commands = config.interaction
rails_cmd = commands[:rails]

# Provisioning and preflight
puts "Provision: #{config.provision}"
puts "Preflight checks: #{config.preflight}"
```

--------------------------------

### Run Application Commands with Custom Ports

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Specify custom ports when running application commands, for example, mapping host port 8000 to container port 3000 for Puma.

```shell
# With custom ports
dip run -p 8000:3000 bundle exec puma
```

--------------------------------

### Initialize InteractionTree

Source: https://github.com/bibendi/dip/blob/master/_autodocs/06-interaction-tree.md

Creates a new InteractionTree instance from interaction definitions. Entries should be keyed by command names and can include a 'subcommands' section for nested commands.

```ruby
interactions = Dip.config.interaction
tree = Dip::InteractionTree.new(interactions)

```

--------------------------------

### Dip SSH Up Command

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Starts an SSH agent container. It supports specifying the SSH key path, Docker volume, and user for the container. By default, it runs in interactive mode.

```bash
dip ssh up
```

```bash
dip ssh add
```

--------------------------------

### List Commands

Source: https://github.com/bibendi/dip/blob/master/_autodocs/07-cli-commands.md

Lists all available interaction commands with their descriptions, providing an overview of Dip's capabilities.

```APIDOC
## ls

### Description
Lists all available interaction commands with their descriptions.

### Method
`ls`

### Endpoint
`dip ls`

### Output:
Formatted list of commands and descriptions

### Example Output:
```
bash     # Open the Bash shell in app's container
rails    # Run Rails command
rails s  # Run Rails server at http://localhost:3000
```
```

--------------------------------

### ProgramRunner.call

Source: https://github.com/bibendi/dip/blob/master/_autodocs/05-command-execution.md

Executes a command using Kernel.exec. It takes the command line, optional environment variables, and options for Kernel.exec.

```APIDOC
## ProgramRunner.call

### Description
Internal runner that executes via `Kernel.exec`.

### Method
Class Method

### Signature
`ProgramRunner.call(cmdline, env: {}, **options) -> void`

### Parameters
#### Parameters
- **cmdline** (String, Array) - Required - Command to execute
- **env** (Hash) - Optional - Environment variables to set (default: {})
- **options** (Hash) - Optional - Options for Kernel.exec
```