fleetcontrol

package
v0.111.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 2, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

README

Fleet Control CLI - Command Reference

A command-line interface for managing New Relic Fleet Control entities including fleets, configurations, deployments, members, and entity queries.

Fleet Control enables centralized management of New Relic agents across your infrastructure, allowing you to:

  • Group entities into fleets for organized management
  • Create and version agent configurations
  • Deploy configurations to fleet members
  • Manage fleet membership with ring-based deployments
  • Query managed and unassigned entities

📑 Table of Contents

📋 Command Hierarchy

Fleet Control commands are organized by resource type for intuitive navigation:

newrelic fleetcontrol
├── fleet                    # Fleet management
│   ├── create              # Create a new fleet
│   ├── get                 # Get fleet details
│   ├── search              # Search fleets
│   ├── update              # Update fleet
│   ├── delete              # Delete fleet(s)
│   └── members             # Manage fleet members
│       ├── add             # Add entities to ring
│       ├── remove          # Remove entities from ring
│       └── list            # List fleet members
│
├── configuration            # Configuration management
│   ├── create              # Create configuration
│   ├── get                 # Get configuration content
│   ├── delete              # Delete configuration
│   └── versions            # Manage configuration versions
│       ├── list            # List all versions
│       ├── add             # Add new version
│       └── delete          # Delete specific version
│
├── deployment               # Deployment management
│   ├── create              # Create deployment
│   ├── update              # Update deployment
│   ├── deploy              # Trigger deployment
│   └── delete              # Delete deployment
│
└── entities                 # Entity queries
    ├── get-managed         # List managed entities
    └── get-unassigned      # List available entities

🔧 Prerequisites

Before using Fleet Control commands, ensure you have the following configured:

Required Environment Variables

Set these environment variables for authentication and authorization:

# Required: Your New Relic User API Key
export NEW_RELIC_API_KEY="NRAK-YOUR-API-KEY-HERE"

# Required: Your New Relic Account ID
export NEW_RELIC_ACCOUNT_ID="your-account-id"

# Optional: Specify region (defaults to US)
export NEW_RELIC_REGION="US"  # or "EU" for European accounts
Getting Your Credentials

  1. API Key: Generate a User API Key from New Relic One → Click your name (bottom-left) → "API Keys" → Create "User" key (not "Browser" or "License")

  2. Account ID: Find it in the New Relic One URL after /accounts/ (e.g., https://one.newrelic.com/accounts/1234567/...) or in Account settings.

Verifying Setup

Test your configuration with a simple command:

# List all fleets (should return empty array or existing fleets)
./bin/darwin/newrelic fleetcontrol fleet search

If you see authentication errors, verify your NEW_RELIC_API_KEY is set correctly. If the issue persists, ensure the user associated with the API key has the necessary capabilities to perform Fleet Control operations.

Organization ID

Most commands accept an optional --organization-id flag. If not provided, the CLI will automatically fetch your organization ID using your API credentials. You can find your organization ID in the New Relic UI under Account Settings.

📋 Command Reference

Fleet Management Commands
fleetcontrol fleet create - Create a New Fleet

Create a fleet to group and manage entities of the same type.

Required Flags:

  • --name - Fleet name
  • --managed-entity-type - Type of entities this fleet will manage
    • Allowed values: HOST, KUBERNETESCLUSTER (case-insensitive)
  • --operating-system - Operating system type (required for HOST fleets only)
    • Allowed values: LINUX, WINDOWS (case-insensitive)
    • Must be specified when creating HOST fleets to ensure proper agent configuration
    • Must NOT be specified for KUBERNETESCLUSTER fleets (Kubernetes manages its own OS)

Optional Flags:

  • --description - Fleet description
  • --product - New Relic product associated with this fleet
  • --tags - Tags in format "key:value1,value2" (can specify multiple times)
  • --organization-id - Organization ID (auto-fetched if not provided)

Examples:

# Create a fleet for Linux hosts
newrelic fleetcontrol fleet create \
  --name "Production Linux Hosts" \
  --managed-entity-type "HOST" \
  --operating-system "LINUX" \
  --description "Production environment Linux host fleet" \
  --product "Infrastructure" \
  --tags "env:prod" \
  --tags "region:us-east-1"

# Create a fleet for Windows hosts
newrelic fleetcontrol fleet create \
  --name "Production Windows Hosts" \
  --managed-entity-type "HOST" \
  --operating-system "WINDOWS" \
  --description "Production environment Windows host fleet" \
  --product "Infrastructure" \
  --tags "env:prod"

# Create a Kubernetes fleet (no --operating-system flag)
newrelic fleetcontrol fleet create \
  --name "K8s Prod Clusters" \
  --managed-entity-type "KUBERNETESCLUSTER" \
  --tags "env:prod,team:platform"

Response:

{
  "status": "success",
  "error": "",
  "id": "fleet-abc-123",
  "name": "Production Linux Hosts",
  "type": "FLEET",
  "managedEntityType": "HOST",
  "operatingSystem": {
    "type": "LINUX"
  },
  "description": "Production environment Linux host fleet",
  "createdAt": 1770977865600,
  "updatedAt": 1770977865882
}
fleetcontrol fleet get - Get Fleet by ID

Retrieve details of a specific fleet by its ID.

Required Flags:

  • --fleet-id - Fleet ID

Examples:

# Get fleet details
newrelic fleetcontrol fleet get --fleet-id "fleet-abc-123"

# With explicit organization ID
newrelic fleetcontrol fleet get \
  --fleet-id "fleet-abc-123" \
  --organization-id "ORG_ID"

Response:

{
  "status": "success",
  "error": "",
  "result": {
    "id": "fleet-abc-123",
    "name": "Production Hosts",
    "managedEntityType": "HOST",
    "description": "Production environment host fleet",
    "createdAt": "2026-01-15T10:30:00Z",
    ...
  }
}
fleetcontrol fleet search - Search for Fleets

Search for fleets using name filters or retrieve all fleets.

Optional Flags:

  • --name-equals - Exact name match (mutually exclusive with --name-contains)
  • --name-contains - Partial name match (mutually exclusive with --name-equals)
  • --organization-id - Organization ID (auto-fetched if not provided)

Note: If neither search flag is provided, returns all fleets.

Examples:

# Get all fleets
newrelic fleetcontrol fleet search

# Search by exact name
newrelic fleetcontrol fleet search --name-equals "Production Hosts"

# Search by name contains
newrelic fleetcontrol fleet search --name-contains "prod"

# Table format
newrelic fleetcontrol fleet search --format text

Response (raw output, no wrapper):

[
  {
    "id": "fleet-abc-123",
    "name": "Production Hosts",
    "managedEntityType": "HOST",
    ...
  },
  {
    "id": "fleet-def-456",
    "name": "Production K8s",
    "managedEntityType": "KUBERNETESCLUSTER",
    ...
  }
]
fleetcontrol fleet update - Update an Existing Fleet

Update fleet properties such as name, description, or tags.

Required Flags:

  • --id - Fleet ID to update

Optional Flags:

  • --name - New fleet name
  • --description - New description
  • --tags - New tags (replaces existing tags)
  • --organization-id - Organization ID (auto-fetched if not provided)

Note: Only provided fields will be updated. Omitted fields remain unchanged.

Examples:

# Update fleet name
newrelic fleetcontrol fleet update \
  --id "fleet-abc-123" \
  --name "Production Hosts - Updated"

# Update description and tags
newrelic fleetcontrol fleet update \
  --id "fleet-abc-123" \
  --description "New description" \
  --tags "env:prod" \
  --tags "updated:yes"

# Update only tags
newrelic fleetcontrol fleet update \
  --id "fleet-abc-123" \
  --tags "env:prod,region:us-west-2"

Response:

{
  "status": "success",
  "error": "",
  "result": {
    "id": "fleet-abc-123",
    "name": "Production Hosts - Updated",
    "description": "New description",
    ...
  }
}
fleetcontrol fleet delete - Delete One or More Fleets

Delete a single fleet or multiple fleets in bulk.

Required Flags (mutually exclusive):

  • --fleet-id - Delete a single fleet
  • --fleet-ids - Delete multiple fleets (comma-separated, requires 2+ IDs)

Validation:

  • Must provide either --fleet-id or --fleet-ids, not both
  • Bulk delete (--fleet-ids) requires at least 2 IDs (use --fleet-id for single deletion)

Examples:

# Delete single fleet
newrelic fleetcontrol fleet delete --fleet-id "fleet-abc-123"

# Bulk delete multiple fleets
newrelic fleetcontrol fleet delete --fleet-ids "fleet-1,fleet-2,fleet-3"

Response (single delete):

{
  "status": "success",
  "error": "",
  "id": "fleet-abc-123"
}

Response (bulk delete):

[
  {
    "status": "success",
    "error": "",
    "id": "fleet-1"
  },
  {
    "status": "success",
    "error": "",
    "id": "fleet-2"
  },
  {
    "status": "failed",
    "error": "failed to delete fleet: fleet not found",
    "id": "fleet-3"
  }
]
Fleet Member Management Commands
fleetcontrol fleet members add - Add Members to Fleet

Add entities to a fleet ring for controlled deployment rollouts.

Required Flags:

  • --fleet-id - Fleet ID to add members to
  • --ring - Ring name within the fleet
  • --entity-ids - Comma-separated list of entity IDs to add

Examples:

# Add members to fleet ring
newrelic fleetcontrol fleet members add \
  --fleet-id "fleet-abc-123" \
  --ring "canary" \
  --entity-ids "entity-1,entity-2,entity-3"

Response:

{
  "status": "success",
  "error": "",
  "result": {
    "fleetId": "fleet-abc-123",
    "ring": "canary",
    "addedEntityIds": ["entity-1", "entity-2", "entity-3"],
    ...
  }
}
fleetcontrol fleet members remove - Remove Members from Fleet

Remove entities from a fleet ring.

Required Flags:

  • --fleet-id - Fleet ID to remove members from
  • --ring - Ring name within the fleet
  • --entity-ids - Comma-separated list of entity IDs to remove

Examples:

# Remove members from fleet ring
newrelic fleetcontrol fleet members remove \
  --fleet-id "fleet-abc-123" \
  --ring "default" \
  --entity-ids "entity-1,entity-2"

Response:

{
  "status": "success",
  "error": "",
  "result": {
    "fleetId": "fleet-abc-123",
    "ring": "default",
    "removedEntityIds": ["entity-1", "entity-2"],
    ...
  }
}
fleetcontrol fleet members list - List Fleet Members

List all entities in a fleet, optionally filtered by ring.

Required Flags:

  • --fleet-id - Fleet ID to list members from

Optional Flags:

  • --ring - Filter by specific ring name
  • --show-tags - Include entity tags in output (default: false)

Examples:

# List all members in a fleet
newrelic fleetcontrol fleet members list --fleet-id "fleet-abc-123"

# List members in a specific ring
newrelic fleetcontrol fleet members list \
  --fleet-id "fleet-abc-123" \
  --ring "canary"

# Include tags in the output
newrelic fleetcontrol fleet members list \
  --fleet-id "fleet-abc-123" \
  --show-tags
Configuration Management Commands
fleetcontrol configuration create - Create a New Configuration

Create a versioned configuration for fleet agents.

Required Flags:

  • --name - Configuration name
  • --agent-type - Type of agent this configuration targets
    • Allowed values: NRInfra, NRDOT, FluentBit, NRPrometheusAgent (case-insensitive)
  • --managed-entity-type - Type of entities this configuration applies to
    • Allowed values: HOST, KUBERNETESCLUSTER (case-insensitive)
  • --operating-system - Operating system type (required for HOST configurations only)
    • Allowed values: LINUX, WINDOWS (case-insensitive)
  • Exactly one of:
    • --configuration-file-path - Path to configuration file (JSON/YAML) - recommended for production
    • --configuration-content - Inline configuration content (JSON/YAML) - for testing/development only

Optional Flags:

  • --organization-id - Organization ID (auto-fetched if not provided)

Validation:

  • Mutually exclusive: Must provide either --configuration-file-path OR --configuration-content, not both
  • --operating-system is required when --managed-entity-type is HOST
  • --operating-system must not be specified when --managed-entity-type is KUBERNETESCLUSTER
  • File path is the recommended approach for production use
  • Inline content should only be used for testing, development, or emergency purposes.

Examples:

# Recommended: Read from file (Linux host)
newrelic fleetcontrol configuration create \
  --name "Production Host Config" \
  --agent-type "NRInfra" \
  --managed-entity-type "HOST" \
  --operating-system "LINUX" \
  --configuration-file-path ./configs/prod-host.json

# Recommended: Read from file (Kubernetes cluster)
newrelic fleetcontrol configuration create \
  --name "Production K8s Config" \
  --agent-type "NRInfra" \
  --managed-entity-type "KUBERNETESCLUSTER" \
  --configuration-file-path ./configs/prod-k8s.json

# Alternative: Inline content (testing only)
newrelic fleetcontrol configuration create \
  --name "Test Config" \
  --agent-type "NRInfra" \
  --managed-entity-type "HOST" \
  --operating-system "LINUX" \
  --configuration-content '{"metrics_interval": 15}'

Response:

{
  "status": "success",
  "error": "",
  "result": {
    "entityGuid": "CONFIG-ABC-123",
    "entityName": "Production Host Config",
    "blobVersionEntity": {
      "version": 1,
      "guid": "VERSION-XYZ-789",
      "blobId": "blob-456"
    },
    ...
  }
}
fleetcontrol configuration get - Get Configuration Content

Retrieve the configuration content for a specific configuration or version.

Required Flags:

  • --configuration-id - Configuration entity ID or version entity ID

Optional Flags:

  • --version - Specific version number to retrieve (defaults to latest if not provided).
  • --mode - Entity mode:
    • ConfigEntity (default) - Use when --configuration-id is a configuration entity ID
    • ConfigVersionEntity - Use when --configuration-id is a version entity ID
  • --organization-id - Organization ID (auto-fetched if not provided)

Note: This command returns raw configuration content on success (no status wrapper) but uses error wrapper on failure.

Examples:

# Get latest version
newrelic fleetcontrol configuration get \
  --configuration-id "CONFIG-ABC-123"

# Get specific version by number
newrelic fleetcontrol configuration get \
  --configuration-id "CONFIG-ABC-123" \
  --version 2

# Get by version entity ID
newrelic fleetcontrol configuration get \
  --configuration-id "VERSION-XYZ-789" \
  --mode "ConfigVersionEntity"

# Table format
newrelic fleetcontrol configuration get \
  --configuration-id "CONFIG-ABC-123" \
  --format text

Response (raw output on success):

{
  "metrics_interval": 15,
  "log_level": "info",
  "custom_attributes": {
    "environment": "production"
  }
}

Response (on failure):

{
  "status": "failed",
  "error": "failed to get configuration: configuration not found"
}
fleetcontrol configuration delete - Delete a Configuration

Delete an entire configuration and all its versions.

Required Flags:

  • --configuration-id - Configuration entity ID to delete

Optional Flags:

  • --organization-id - Organization ID (auto-fetched if not provided)

Warning: This deletes the configuration and all associated versions permanently.

Examples:

# Delete configuration
newrelic fleetcontrol configuration delete \
  --configuration-id "CONFIG-ABC-123"

Response:

{
  "status": "success",
  "error": "",
  "id": "CONFIG-ABC-123"
}
Configuration Version Commands
fleetcontrol configuration versions list - List All Configuration Versions

Retrieve version history for a configuration.

Required Flags:

  • --configuration-id - Configuration entity ID (not version ID)

Optional Flags:

  • --organization-id - Organization ID (auto-fetched if not provided)

Validation:

  • Returns error if no versions are found (invalid ID or configuration with no versions).

Examples:

# List all versions
newrelic fleetcontrol configuration versions list \
  --configuration-id "CONFIG-ABC-123"

# With explicit organization ID
newrelic fleetcontrol configuration versions list \
  --configuration-id "CONFIG-ABC-123" \
  --organization-id "ORG_ID"

Response:

{
  "status": "success",
  "error": "",
  "result": {
    "versions": [
      {
        "version": 3,
        "guid": "VERSION-XYZ-789",
        "blobId": "blob-789",
        "createdAt": "2026-01-20T14:30:00Z"
      },
      {
        "version": 2,
        "guid": "VERSION-XYZ-456",
        "blobId": "blob-456",
        "createdAt": "2026-01-15T10:00:00Z"
      },
      {
        "version": 1,
        "guid": "VERSION-XYZ-123",
        "blobId": "blob-123",
        "createdAt": "2026-01-10T09:00:00Z"
      }
    ]
  }
}

Error (no versions found):

{
  "status": "failed",
  "error": "no version details found, please check the ID of the configuration entity provided"
}
fleetcontrol configuration versions add - Add a New Version to Configuration

Add a new version to an existing configuration.

Required Flags:

  • --configuration-id - Configuration entity ID
  • Exactly one of:
    • --configuration-file-path - Path to configuration file (JSON/YAML) - recommended for production
    • --configuration-content - Inline configuration content (JSON/YAML) - for testing/development only

Optional Flags:

  • --organization-id - Organization ID (auto-fetched if not provided)

Validation:

  • Mutually exclusive: Must provide either --configuration-file-path OR --configuration-content, not both
  • File path is the recommended approach for production use
  • Inline content should only be used for testing, development, or emergency purposes.

Examples:

# Recommended: Read from file
newrelic fleetcontrol configuration versions add \
  --configuration-id "CONFIG-ABC-123" \
  --configuration-file-path ./configs/v2-config.json

# Alternative: Inline content (testing only)
newrelic fleetcontrol configuration versions add \
  --configuration-id "CONFIG-ABC-123" \
  --configuration-content '{"metrics_interval": 30, "updated": true}'

Response:

{
  "status": "success",
  "error": "",
  "result": {
    "blobVersionEntity": {
      "version": 2,
      "guid": "VERSION-XYZ-456",
      "blobId": "blob-456"
    },
    "entityGuid": "CONFIG-ABC-123",
    ...
  }
}
fleetcontrol configuration versions delete - Delete a Configuration Version

Delete a specific version of a configuration.

Required Flags:

  • --version-id - Version entity ID to delete

Optional Flags:

  • --organization-id - Organization ID (auto-fetched if not provided)

Note: The version ID is the entity ID of the specific version (found in versions list output), not the configuration ID.

Examples:

# Delete specific version
newrelic fleetcontrol configuration versions delete \
  --version-id "VERSION-XYZ-456"

Response:

{
  "status": "success",
  "error": "",
  "id": "VERSION-XYZ-456"
}
Deployment Management Commands
fleetcontrol deployment create - Create a Deployment

Create a deployment to roll out configurations to fleet members. Supports single or multiple agents.

Required Flags:

  • --fleet-id - Fleet ID to deploy to
  • --name - Deployment name
  • Either (new syntax - supports multiple agents):
    • --agent - Agent specification in format "AgentType:Version:ConfigVersionID1,ConfigVersionID2" (can specify multiple times for multiple agents)
  • Or (legacy syntax - SINGLE agent only):
    • --agent-type - Agent type (e.g., NRInfra, NRDOT) - creates ONE agent
    • --agent-version - Agent version (e.g., 1.70.0, 2.0.0, or * for KUBERNETESCLUSTER fleets only)
    • --configuration-version-ids - Configuration version IDs to deploy (comma-separated values for multiple configs on the same agent)

Optional Flags:

  • --description - Deployment description
  • --tags - Tags in format "key:value1,value2" (can specify multiple times)

Validation:

  • Must use either --agent OR all three legacy flags (--agent-type, --agent-version, --configuration-version-ids)
  • Cannot mix syntaxes - using --agent with any legacy flag will error
  • Agent version "*" (wildcard) is only allowed for KUBERNETESCLUSTER fleets
    • HOST fleets must specify an explicit version (e.g., "1.70.0")
    • The CLI validates fleet type and rejects wildcards for HOST fleets with a clear error message.

Examples:

# New syntax: Single agent
newrelic fleetcontrol deployment create \
  --fleet-id "fleet-abc-123" \
  --name "Production Rollout v2" \
  --agent "NRInfra:1.70.0:version-1,version-2" \
  --description "Rolling out updated monitoring configuration" \
  --tags "env:prod" \
  --tags "release:v1.2.3"

# New syntax: Multiple agents (Infrastructure + .NET)
newrelic fleetcontrol deployment create \
  --fleet-id "fleet-abc-123" \
  --name "Multi-Agent Deployment" \
  --agent "NRInfra:1.70.0:version-1,version-2" \
  --agent "NRDOT:2.0.0:version-3" \
  --description "Deploying Infrastructure and .NET agent configs"

# Legacy syntax: SINGLE agent with one config (still supported for backward compatibility)
newrelic fleetcontrol deployment create \
  --fleet-id "fleet-abc-123" \
  --name "Single Config Deployment" \
  --agent-type "NRInfra" \
  --agent-version "1.70.0" \
  --configuration-version-ids "version-1" \
  --description "One agent, one configuration"

# Legacy syntax: SINGLE agent with multiple configs (comma-separated)
# This creates ONE Infrastructure agent with TWO configuration versions
newrelic fleetcontrol deployment create \
  --fleet-id "fleet-abc-123" \
  --name "Multi-Config Single Agent" \
  --agent-type "NRInfra" \
  --agent-version "1.70.0" \
  --configuration-version-ids "version-1,version-2" \
  --description "One agent, multiple configurations"

# Kubernetes fleet with wildcard version (only works for KUBERNETESCLUSTER fleets)
newrelic fleetcontrol deployment create \
  --fleet-id "k8s-fleet-456" \
  --name "K8s Wildcard Deployment" \
  --agent "NRInfra:*:version-1,version-2" \
  --description "Using wildcard version for Kubernetes"

# IMPORTANT DIFFERENCE: New vs Legacy Syntax
# Legacy: Can only create ONE agent type per deployment
# New: Can create MULTIPLE agent types per deployment

# ❌ Cannot do this with legacy syntax (would need two separate deployments):
# --agent-type "NRInfra" ... AND --agent-type "NRDOT" ...

# ✅ Can do this with new syntax (one deployment with multiple agents):
newrelic fleetcontrol deployment create \
  --fleet-id "fleet-abc-123" \
  --name "Multi-Agent Deployment" \
  --agent "NRInfra:1.70.0:version-1,version-2" \
  --agent "NRDOT:2.0.0:version-3" \
  --description "Two different agent types in one deployment"

Response:

{
  "status": "success",
  "error": "",
  "result": {
    "id": "deployment-xyz-789",
    "name": "Production Rollout v2",
    "fleetId": "fleet-abc-123",
    "configurationVersionIds": ["version-1", "version-2"],
    ...
  }
}
fleetcontrol deployment update - Update a Deployment

Update an existing deployment's properties, including agent configurations. Note that a deployment can only be updated before it is triggered; a deployment that has already been completed cannot be updated.

Required Flags:

  • --deployment-id - Deployment ID to update

Optional Flags:

  • --name - New deployment name
  • Either (new syntax - supports multiple agents):
    • --agent - Agent specification in format "AgentType:Version:ConfigVersionID1,ConfigVersionID2" (can specify multiple times for multiple agents)
  • Or (legacy syntax - SINGLE agent only):
    • --configuration-version-ids - Configuration version IDs to update (comma-separated values for multiple configs on the same agent)
  • --description - New description
  • --tags - New tags (replaces existing tags)

Important Notes:

  • Only provided fields will be updated. Omitted fields remain unchanged.
  • Must use either --agent OR --configuration-version-ids, not both
  • Using --agent allows you to update agent types, versions, and configuration versions
  • Using --configuration-version-ids (legacy) only updates configuration versions
  • Agent version "*" (wildcard) validation is applied during update but may be limited by API constraints.

Examples:

# New syntax: Update agents with new versions
newrelic fleetcontrol deployment update \
  --deployment-id "deployment-xyz-789" \
  --agent "NRInfra:1.71.0:version-3,version-4" \
  --agent "NRDOT:2.1.0:version-5"

# New syntax: Update single agent
newrelic fleetcontrol deployment update \
  --deployment-id "deployment-xyz-789" \
  --agent "NRInfra:1.71.0:version-3,version-4"

# Legacy syntax: Update configuration versions only
newrelic fleetcontrol deployment update \
  --deployment-id "deployment-xyz-789" \
  --configuration-version-ids "version-3,version-4"

# Update deployment name
newrelic fleetcontrol deployment update \
  --deployment-id "deployment-xyz-789" \
  --name "Production Rollout v3"

# Update multiple fields
newrelic fleetcontrol deployment update \
  --deployment-id "deployment-xyz-789" \
  --name "Updated Deployment" \
  --description "New description" \
  --tags "env:prod,updated:yes"

Response:

{
  "status": "success",
  "error": "",
  "result": {
    "id": "deployment-xyz-789",
    "name": "Production Rollout v3",
    "configurationVersionIds": ["version-3", "version-4"],
    ...
  }
}
fleetcontrol deployment deploy - Trigger Deployment

Trigger deployment to roll out configurations across fleet rings.

Required Flags:

  • --deployment-id - Deployment ID to trigger
  • --rings-to-deploy - Comma-separated list of ring names to deploy to

Examples:

# Deploy to multiple rings
newrelic fleetcontrol deployment deploy \
  --deployment-id "deployment-xyz-789" \
  --rings-to-deploy "canary,default"

# Deploy to a single ring
newrelic fleetcontrol deployment deploy \
  --deployment-id "deployment-xyz-789" \
  --rings-to-deploy "default"
fleetcontrol deployment delete - Delete a Deployment

Delete a fleet deployment. This operation cannot be undone and will remove the deployment. The deployment must not be actively in progress.

Required Flags:

  • --deployment-id - Deployment ID to delete

Examples:

# Delete a deployment
newrelic fleetcontrol deployment delete \
  --deployment-id "deployment-xyz-789"

Response:

{
  "status": "success",
  "error": "",
  "id": "deployment-xyz-789"
}
Entity Query Commands

These commands help you identify which entities are managed by fleets and which are available for fleet management.

fleetcontrol entities get-managed - List Managed Entities

Retrieve all entities that are currently managed by any fleet in the account.

Managed entities are identified by having both:

  • tags.nr.fleet IS NOT NULL
  • tags.nr.supervisor IS NOT NULL

Optional Flags:

  • --entity-type - Filter by entity type (e.g., HOST, KUBERNETESCLUSTER)
  • --limit - Maximum number of entities to return (default: 100)
  • --include-tags - Include entity tags in output (default: false)

Examples:

# Get all managed entities
newrelic fleetcontrol entities get-managed

# Limit results to 50 entities
newrelic fleetcontrol entities get-managed --limit 50

# Filter by entity type
newrelic fleetcontrol entities get-managed --entity-type HOST

# Include tags in output
newrelic fleetcontrol entities get-managed --include-tags
fleetcontrol entities get-unassigned - List Unassigned Entities

Retrieve all entities that are NOT currently managed by any fleet but are available for fleet management.

Unassigned entities are identified by having:

  • tags.nr.fleet IS NULL
  • tags.nr.supervisor IS NOT NULL

This command helps you identify which entities can be added to a fleet.

Optional Flags:

  • --entity-type - Filter by entity type (e.g., HOST, KUBERNETESCLUSTER)
  • --limit - Maximum number of entities to return (default: 100)
  • --include-tags - Include entity tags in output (default: false)

Examples:

# Get all unassigned entities
newrelic fleetcontrol entities get-unassigned

# Limit results to 50 entities
newrelic fleetcontrol entities get-unassigned --limit 50

# Filter by entity type
newrelic fleetcontrol entities get-unassigned --entity-type HOST

# Include tags in output
newrelic fleetcontrol entities get-unassigned --include-tags

📤 Understanding Response Formats

All commands return consistent JSON output for easy parsing and automation.

Success Response

Most commands wrap results with status and error fields:

{
  "status": "success",
  "error": "",
  "result": {
    "entityGuid": "ABC123DEF456",
    "name": "Production Fleet",
    ...
  }
}

Delete operations:

{
  "status": "success",
  "error": "",
  "id": "deleted-entity-id"
}

Bulk operations return an array:

[
  {
    "status": "success",
    "error": "",
    "id": "fleet-1"
  },
  {
    "status": "failed",
    "error": "failed to delete fleet: not found",
    "id": "fleet-2"
  }
]
Failure Response
{
  "status": "failed",
  "error": "failed to create fleet: organization ID required"
}
Commands with Raw Output

Search and get-configuration return raw data (no wrapper) for table formatting:

[
  {
    "id": "fleet-123",
    "name": "Production Fleet",
    ...
  }
]

Errors from these commands still use the status/error wrapper.

🔍 Working with JSON Responses

Using jq for Response Parsing

Extract data from success:

# Get entityGuid from create
newrelic fleetcontrol configuration create ... | jq -r '.result.entityGuid'

# Get version number
newrelic fleetcontrol configuration versions add ... | jq -r '.result.blobVersionEntity.version'

# Get ID from delete
newrelic fleetcontrol fleet delete --fleet-id abc123 | jq -r '.id'

Check status before extracting:

# Extract only if successful
newrelic fleetcontrol fleet create ... | \
  jq -r 'select(.status == "success") | .result.entityGuid'

# Show error on failure, result on success
newrelic fleetcontrol fleet create ... | \
  jq -r 'if .status == "success" then .result.entityGuid else .error end'

Store result with error handling:

OUTPUT=$(newrelic fleetcontrol fleet create ...)
STATUS=$(echo "$OUTPUT" | jq -r '.status')

if [ "$STATUS" = "success" ]; then
  GUID=$(echo "$OUTPUT" | jq -r '.result.entityGuid')
  echo "Created: $GUID"
else
  ERROR=$(echo "$OUTPUT" | jq -r '.error')
  echo "Failed: $ERROR"
  exit 1
fi
Practical Workflow Examples

Create fleet and store ID:

# Create fleet and extract ID
FLEET_ID=$(newrelic fleetcontrol fleet create \
  --name "My Fleet" \
  --managed-entity-type "HOST" | jq -r '.result.id')

echo "Created fleet: $FLEET_ID"

Create configuration and add version:

# Create configuration
CONFIG_GUID=$(newrelic fleetcontrol configuration create \
  --name "My Config" \
  --agent-type "NRInfra" \
  --managed-entity-type "HOST" \
  --configuration-file-path ./config.json | jq -r '.result.entityGuid')

# Add a new version
newrelic fleetcontrol configuration versions add \
  --configuration-id "$CONFIG_GUID" \
  --configuration-file-path ./config-v2.json

List and filter fleets:

# Get all production fleets
newrelic fleetcontrol fleet search | jq '.[] | select(.name | contains("prod"))'

# Count total fleets
newrelic fleetcontrol fleet search | jq 'length'

# Get fleet names only
newrelic fleetcontrol fleet search | jq -r '.[].name'

Find entities to add to fleet:

# Get unassigned hosts
ENTITIES=$(newrelic fleetcontrol entities get-unassigned \
  --entity-type HOST | jq -r '.[].id' | head -3 | paste -sd "," -)

# Add them to fleet
newrelic fleetcontrol fleet members add \
  --fleet-id "fleet-abc-123" \
  --ring "production" \
  --entity-ids "$ENTITIES"

🎯 Validation Rules Reference

Agent Types

Used in configuration commands. Values are case-insensitive.

Allowed values:

  • NRInfra - New Relic Infrastructure agent
  • NRDOT - New Relic .NET agent
  • FluentBit - Fluent Bit log forwarder
  • NRPrometheusAgent - New Relic Prometheus agent

Example:

--agent-type "nrinfra"  # Case-insensitive, works fine
Managed Entity Types

Used in fleet and configuration commands. Values are case-insensitive.

Allowed values:

  • HOST - Physical or virtual hosts
  • KUBERNETESCLUSTER - Kubernetes clusters

Example:

--managed-entity-type "host"  # Case-insensitive, works fine
Configuration Modes

Used in configuration get command. Values are case-insensitive.

Allowed values:

  • ConfigEntity (default) - Query by configuration entity ID
  • ConfigVersionEntity - Query by version entity ID

Example:

--mode "configversionentity"  # Case-insensitive, works fine
Tags Format

Tags must be in format "key:value1,value2".

Examples:

# Single tag with single value
--tags "env:prod"

# Single tag with multiple values
--tags "env:prod,staging"

# Multiple tags
--tags "env:prod" --tags "team:platform" --tags "region:us-east-1"

# Result parsed as:
# [
#   {Key: "env", Values: ["prod"]},
#   {Key: "team", Values: ["platform"]},
#   {Key: "region", Values: ["us-east-1"]}
# ]
Agent Specification Format

Used in deployment create command with the --agent flag. Format: "AgentType:Version:ConfigVersionID1,ConfigVersionID2,..."

Format Components:

  • AgentType - The type of agent (e.g., NRInfra, NRDOT, FluentBit, NRPrometheusAgent)
  • Version - The agent version to deploy (e.g., 1.70.0, 2.0.0, or * for KUBERNETESCLUSTER fleets only)
    • Use explicit versions like "1.70.0" for HOST fleets
    • Use "*" (wildcard) only for KUBERNETESCLUSTER fleets
    • The CLI validates fleet type before allowing wildcard versions
  • ConfigVersionIDs - Comma-separated list of configuration version IDs (no spaces)

Examples:

# Single agent with one configuration version
--agent "NRInfra:1.70.0:version-abc-123"

# Single agent with multiple configuration versions
--agent "NRInfra:1.70.0:version-1,version-2,version-3"

# Multiple agents (Infrastructure and .NET)
--agent "NRInfra:1.70.0:version-1,version-2" \
--agent "NRDOT:2.0.0:version-3"

# Multiple agents (Infrastructure, .NET, and Fluent Bit)
--agent "NRInfra:1.70.0:config-infra-v1" \
--agent "NRDOT:2.0.0:config-dotnet-v1" \
--agent "FluentBit:1.9.0:config-logs-v1"

# Wildcard version for Kubernetes fleet (only valid for KUBERNETESCLUSTER type)
--agent "NRInfra:*:config-k8s-v1"

Common Errors:

# ❌ Incorrect: Spaces in format
--agent "NRInfra : 1.70.0 : version-1, version-2"

# ✅ Correct: No spaces
--agent "NRInfra:1.70.0:version-1,version-2"

# ❌ Incorrect: Missing version
--agent "NRInfra:version-1,version-2"

# ✅ Correct: All three parts present
--agent "NRInfra:1.70.0:version-1,version-2"

# ❌ Incorrect: Using wildcard "*" with HOST fleet
--agent "NRInfra:*:version-1"  # on a HOST fleet
# Error: agent version '*' (wildcard) is not supported for HOST fleets.
#        Please specify an explicit version (e.g., '1.70.0').

# ✅ Correct: Explicit version for HOST fleet
--agent "NRInfra:1.70.0:version-1"

# ✅ Correct: Wildcard for KUBERNETESCLUSTER fleet
--agent "NRInfra:*:version-1"  # on a KUBERNETESCLUSTER fleet

The syntax using separate flags can be preferred in the case of single-agent deployments:

# Legacy syntax (creates ONE agent with multiple configs)
--agent-type "NRInfra" \
--agent-version "1.70.0" \
--configuration-version-ids "version-1,version-2"
# Result: 1 Infrastructure agent with 2 configuration versions

# New syntax (can create MULTIPLE agents)
--agent "NRInfra:1.70.0:version-1,version-2"
# Result: 1 Infrastructure agent with 2 configuration versions

# New syntax (multiple agents - NOT possible with legacy syntax)
--agent "NRInfra:1.70.0:version-1,version-2" \
--agent "NRDOT:2.0.0:version-3"
# Result: 2 agents (Infrastructure + .NET)

Important Notes:

  • The --agent flag and legacy flags are mutually exclusive - choose one syntax or the other, not both
  • Legacy syntax limitation: Can only create ONE agent type per deployment. To deploy multiple agent types (e.g., Infrastructure + .NET), use the new --agent syntax
  • --configuration-version-ids in legacy syntax: Comma-separated IDs all belong to the same single agent, not multiple agents

🐛 Troubleshooting

Common Issues
Problem Solution
"Authentication failed" Verify NEW_RELIC_API_KEY is set correctly. Ensure it's a User API key, not Browser or License key.
"Account not found" Check NEW_RELIC_ACCOUNT_ID is correct. Find it in New Relic UI or URL.
"required flag not set" Ensure flag syntax is correct: --flag-name value or --flag-name=value (not flag-name=value)
"invalid value for flag" Check validation rules above. Values may need to match allowed values (case-insensitive)
"mutually exclusive flags" Only one of the mutually exclusive flags should be provided (e.g., --fleet-id OR --fleet-ids, not both). For deployments, use either --agent or all three legacy flags, not a mix.
"agent version '*' not supported for HOST fleets" Wildcard version ("*") is only allowed for KUBERNETESCLUSTER fleets. Use an explicit version (e.g., "1.70.0") for HOST fleets.
"--configuration-version-ids is required" When using legacy deployment syntax, you must provide all three flags: --agent-type, --agent-version, AND --configuration-version-ids.
"no version details found" Configuration ID is invalid or has no versions. Verify ID is correct using search command
File not found error When using --configuration-file-path, ensure the file path is correct and file exists
"organization ID required" Provide --organization-id explicitly if auto-fetch fails
Empty response Check that entity exists using search or get commands
JSON parse errors Ensure JSON/YAML configuration content is valid. Test with jq or YAML linter
Flag Syntax Examples

Correct:

--flag-name value
--flag-name=value
--flag-name "value with spaces"

Incorrect:

flag-name=value        # Missing -- prefix
-flag-name value       # Single dash instead of double
Validation Errors

When you see "invalid value for flag", check:

  1. Value is in the allowed values list (see Validation Rules Reference)
  2. Spelling is correct (validation is case-insensitive but value must be in the list)
  3. No extra spaces or quotes

Example validation error:

{
  "status": "failed",
  "error": "invalid value 'KUBERNETES' for flag --managed-entity-type: must be one of [HOST, KUBERNETESCLUSTER]"
}

Solution: Use KUBERNETESCLUSTER instead of KUBERNETES.

Debug Mode

Enable verbose logging for troubleshooting:

# Set log level to debug
export NEW_RELIC_CLI_LOG_LEVEL=debug

# Run command
newrelic fleetcontrol fleet create --name "Test"

📁 Directory Structure

internal/fleetcontrol/
├── README.md                                     # This file - Command reference
├── command.go                                    # Main entry point with command hierarchy
├── command_framework.go                          # Core framework
├── command_flags_generated.go                    # Manually maintained typed flag accessors
├── command_fleet.go                              # Command registration
├── helpers.go                                    # Shared utility functions
│
├── configs/                                      # YAML configuration files
│   ├── fleet_management_create.yaml
│   ├── fleet_management_update.yaml
│   ├── fleet_management_delete.yaml
│   ├── fleet_management_get.yaml
│   ├── fleet_management_search.yaml
│   ├── fleet_members_add.yaml
│   ├── fleet_members_remove.yaml
│   ├── fleet_members_list.yaml
│   ├── fleet_configuration_create.yaml
│   ├── fleet_configuration_get.yaml
│   ├── fleet_configuration_delete.yaml
│   ├── fleet_configuration_version_list.yaml
│   ├── fleet_configuration_version_add.yaml
│   ├── fleet_configuration_version_delete.yaml
│   ├── fleet_deployment_create.yaml
│   ├── fleet_deployment_update.yaml
│   ├── fleet_deployment_deploy.yaml
│   ├── fleet_deployment_delete.yaml
│   ├── fleet_entities_get_managed.yaml
│   └── fleet_entities_get_unassigned.yaml
│
└── Handler implementation files (one per command)

📚 Additional Resources

New Relic Documentation

Documentation

Overview

Package fleetcontrol provides commands for managing New Relic Fleet Control resources.

The fleetcontrol package allows users to manage fleets and their associated entities through the New Relic CLI. It supports operations such as creating, updating, and deleting fleets, as well as managing fleet members.

Package fleetcontrol Typed flag accessors for each command - provides type-safe, zero-hardcoded-string access to flags

IMPORTANT: This file is MANUALLY MAINTAINED following a strict pattern. When adding a new command: 1. Create the YAML config file in configs/ (e.g., fleet_foo_bar.yaml) 2. Create the handler file (e.g., fleet_foo_bar.go) 3. Add typed flag accessors here following the existing pattern:

  • Create a <CommandName>Flags struct with fields matching your YAML flags
  • Create a method on *FlagValues that returns the struct
  • Use fv.GetString(), fv.GetStringSlice(), fv.GetBool(), etc. to retrieve values

4. Register the handler in command_fleet.go's appropriate init function

Example pattern: 

type MyCommandFlags struct {
    FlagName string
}
func (fv *FlagValues) MyCommand() MyCommandFlags {
    return MyCommandFlags{
        FlagName: fv.GetString("flag-name"),
    }
}

Index

Constants

This section is empty.

Variables

View Source 
var (
	// Command represents the fleetcontrol command
	Command = &cobra.Command{
		Use:   "fleetcontrol",
		Short: "Manage New Relic Fleet Control resources",
		Long: `The fleetcontrol command provides subcommands for managing Fleet Control resources.
Fleet Control allows you to organize and manage collections of entities such as hosts
and Kubernetes clusters.`,
	}
)

Functions

func BuildCommand 

func BuildCommand(def CommandDefinition, handler CommandHandler) *cobra.Command

BuildCommand creates a cobra command from a CommandDefinition This sets up all flags, validation, and wires up the handler

Parameters:

  • def: The command definition from YAML
  • handler: The function that implements the command logic

Returns:

  • A fully configured cobra.Command

func GetOrganizationID 

func GetOrganizationID(providedOrgID string) string

GetOrganizationID retrieves the organization ID from the provided value or fetches it from the API. This is used by commands that need an organization ID but make it optional in their flags.

Parameters:

  • providedOrgID: The organization ID provided by the user (may be empty)

Returns:

  • The organization ID (either provided or fetched)

func MapConfigurationMode 

func MapConfigurationMode(modeStr string) (fleetcontrol.GetConfigurationMode, error)

MapConfigurationMode converts a validated mode string to the client library type. This function should ONLY be called after YAML validation has confirmed the value is allowed.

Parameters:

  • modeStr: The mode string (already validated by framework)

Returns:

  • The corresponding GetConfigurationMode
  • Error if the mode is not recognized (should never happen after YAML validation)

func MapManagedEntityType 

func MapManagedEntityType(typeStr string) (fleetcontrol.FleetControlManagedEntityType, error)

MapManagedEntityType converts a validated managed entity type string to the client library type. This function should ONLY be called after YAML validation has confirmed the value is allowed.

Parameters:

  • typeStr: The managed entity type string (already validated by framework)

Returns:

  • The corresponding FleetControlManagedEntityType
  • Error if the type is not recognized (should never happen after YAML validation)

func MapOperatingSystemType 

func MapOperatingSystemType(osStr string) (fleetcontrol.FleetControlOperatingSystemType, error)

MapOperatingSystemType converts a validated operating system type string to the client library type. This function should ONLY be called after YAML validation has confirmed the value is allowed.

Parameters:

  • osStr: The operating system type string (already validated by framework)

Returns:

  • The corresponding FleetControlOperatingSystemType
  • Error if the type is not recognized (should never happen after YAML validation)

func MapScopeType 

func MapScopeType(typeStr string) (fleetcontrol.FleetControlEntityScope, error)

MapScopeType converts a validated scope type string to the client library type. This function should ONLY be called after YAML validation has confirmed the value is allowed.

Parameters:

  • typeStr: The scope type string (already validated by framework)

Returns:

  • The corresponding FleetControlEntityScope
  • Error if the type is not recognized (should never happen after YAML validation)

func ParseAgentSpec 

func ParseAgentSpec(agentSpec string) (fleetcontrol.FleetControlAgentInput, error)

ParseAgentSpec parses an agent specification string into a FleetControlAgentInput struct. Agent specs are used to define agent configurations for deployments.

Format: "AgentType:Version:ConfigVersionID1,ConfigVersionID2,..."

  • AgentType: The type of agent (e.g., NRInfra, NRDOT)
  • Version: The agent version (e.g., 1.70.0, 2.0.0)
  • ConfigVersionIDs: Comma-separated list of configuration version IDs

Parameters:

  • agentSpec: Agent specification string to parse

Returns:

  • FleetControlAgentInput struct
  • Error if format is invalid

Example: 

agent, err := ParseAgentSpec("NRInfra:1.70.0:version1,version2")
// Returns: {AgentType: "NRInfra", Version: "1.70.0", ConfigurationVersionList: [{ID: "version1"}, {ID: "version2"}]}

func ParseTags 

func ParseTags(tagStrings []string) ([]fleetcontrol.FleetControlTagInput, error)

ParseTags converts tag strings in the format "key:value1,value2" into FleetControlTagInput structs. Tags are used to organize and categorize fleet resources.

Format: Each tag string should be "key:value1,value2" where:

  • key: The tag key (required, cannot be empty)
  • value1,value2: Comma-separated values for this key (required, cannot be empty)

Parameters:

  • tagStrings: Array of tag strings to parse

Returns:

  • Array of FleetControlTagInput structs
  • Error if any tag has invalid format

Example: 

tags, err := ParseTags([]string{"env:prod,staging", "team:platform"})
// Returns: [{Key: "env", Values: ["prod", "staging"]}, {Key: "team", Values: ["platform"]}]

func PrintConfigurationDeleteSuccess 

func PrintConfigurationDeleteSuccess(id string) error

PrintConfigurationDeleteSuccess outputs successful configuration delete operation with status and error fields. Uses custom JSON marshaling to preserve field order.

Parameters:

  • id: The ID of the deleted configuration

Returns:

  • Error from printJSON (typically nil)

func PrintConfigurationSuccess 

func PrintConfigurationSuccess(result interface{}) error

PrintConfigurationSuccess outputs successful configuration data wrapped with status and error fields. Uses custom JSON marshaling to preserve field order.

Parameters:

  • result: The configuration result to wrap and print

Returns:

  • Error from printJSON (typically nil)

func PrintDeleteBulkSuccess 

func PrintDeleteBulkSuccess(results []FleetDeleteResponseWrapper) error

PrintDeleteBulkSuccess outputs successful bulk delete operations as a list. Each element in the list has status and error fields. Uses custom JSON marshaling to preserve field order.

Parameters:

  • results: The list of delete results to print

Returns:

  • Error from printJSON (typically nil)

func PrintDeleteSuccess 

func PrintDeleteSuccess(id string) error

PrintDeleteSuccess outputs successful delete operation with status and error fields. Uses custom JSON marshaling to preserve field order.

Parameters:

  • id: The ID of the deleted fleet

Returns:

  • Error from printJSON (typically nil)

func PrintDeploymentDeleteSuccess 

func PrintDeploymentDeleteSuccess(id string) error

PrintDeploymentDeleteSuccess outputs successful deployment delete operation with status and error fields. Uses custom JSON marshaling to preserve field order.

Parameters:

  • id: The ID of the deleted deployment

Returns:

  • Error from printJSON (typically nil)

func PrintDeploymentSuccess 

func PrintDeploymentSuccess(result interface{}) error

PrintDeploymentSuccess outputs successful deployment data wrapped with status and error fields. Uses custom JSON marshaling to preserve field order.

Parameters:

  • result: The deployment result to wrap and print

Returns:

  • Error from printJSON (typically nil)

func PrintError 

func PrintError(err error) error

PrintError outputs an error as JSON with "status" and "error" keys. This allows errors to be parsed by consumers expecting JSON output. Uses custom JSON marshaling to ensure field order: status first, then error.

Parameters:

  • err: The error to print

Returns:

  • Error from output.Print (typically nil)

func PrintFleetListSuccess 

func PrintFleetListSuccess(fleets []FleetEntityOutput) error

PrintFleetListSuccess outputs a successful list of fleets wrapped with status and error fields. Uses custom JSON marshaling to preserve field order.

Parameters:

  • fleets: The list of fleet entities to wrap and print

Returns:

  • Error from printJSON (typically nil)

func PrintFleetSuccess 

func PrintFleetSuccess(fleet *FleetEntityOutput) error

PrintFleetSuccess outputs successful fleet data wrapped with status and error fields. This provides a consistent response structure: status="success", error="", <fleet fields> Uses custom JSON marshaling to preserve field order.

Parameters:

  • fleet: The fleet entity output to wrap and print

Returns:

  • Error from printJSON (typically nil)

func PrintMemberSuccess 

func PrintMemberSuccess(result interface{}) error

PrintMemberSuccess outputs successful member operation data wrapped with status and error fields. Uses custom JSON marshaling to preserve field order.

Parameters:

  • result: The member operation result to wrap and print

Returns:

  • Error from printJSON (typically nil)

func ValidateAgentVersionsForFleet 

func ValidateAgentVersionsForFleet(fleetID string, agents []fleetcontrol.FleetControlAgentInput) error

ValidateAgentVersionsForFleet validates that agent versions are compatible with the fleet type. The "*" wildcard version is only allowed for KUBERNETESCLUSTER fleets, not HOST fleets.

Parameters:

  • fleetID: The ID of the fleet to validate against
  • agents: The agent configurations to validate

Returns:

  • Error if validation fails (e.g., "*" used with HOST fleet)

Types

type AddMembersFlags 

type AddMembersFlags struct {
	FleetID   string
	Ring      string
	EntityIDs []string
}

AddMembersFlags provides typed access to 'add' (members) command flags

type AddVersionFlags 

type AddVersionFlags struct {
	ConfigurationID       string
	OrganizationID        string
	ConfigurationFilePath string // File content from path
	ConfigurationContent  string // Inline content
}

AddVersionFlags provides typed access to 'add' (configuration versions) command flags

type CommandConfig 

type CommandConfig struct {
	Commands []CommandDefinition `yaml:"commands"`
}

CommandConfig represents the entire command configuration It contains all command definitions loaded from YAML files

func LoadCommandConfig 

func LoadCommandConfig() (*CommandConfig, error)

LoadCommandConfig loads and parses all command configuration YAML files This reads from the embedded configs directory Config file names match their handler file names (e.g., fleet_management_create.yaml)

Returns:

  • CommandConfig containing all command definitions
  • Error if loading or parsing fails

type CommandDefinition 

type CommandDefinition struct {
	Name    string           `yaml:"name"`    // Command name (e.g., "create", "update")
	Short   string           `yaml:"short"`   // Short one-line description
	Long    string           `yaml:"long"`    // Detailed multi-line description
	Example string           `yaml:"example"` // Usage examples
	Flags   []FlagDefinition `yaml:"flags"`   // Command flags
}

CommandDefinition represents a single command definition from YAML Each command has metadata (name, description, examples) and flag definitions

func GetCommandDefinition 

func GetCommandDefinition(config *CommandConfig, name string) *CommandDefinition

GetCommandDefinition finds a command definition by name This is used to look up specific commands from the loaded configuration

Parameters:

  • config: The loaded command configuration
  • name: The command name to find

Returns:

  • The command definition, or nil if not found

type CommandHandler 

type CommandHandler func(cmd *cobra.Command, args []string, flags *FlagValues) error

CommandHandler is a function that handles command execution All command handlers must match this signature

Parameters:

  • cmd: The cobra command being executed
  • args: Positional arguments (rarely used in this CLI)
  • flags: Validated flag values accessible through typed accessors

Returns:

  • Error if command execution fails

type ConfigurationDeleteResponseWrapper 

type ConfigurationDeleteResponseWrapper struct {
	Status string `json:"status"`
	Error  string `json:"error"`
	ID     string `json:"id,omitempty"`
}

ConfigurationDeleteResponseWrapper wraps configuration delete result with consistent status and error fields.

type ConfigurationResponseWrapper 

type ConfigurationResponseWrapper struct {
	Status string      `json:"status"`
	Error  string      `json:"error"`
	Result interface{} `json:"result,omitempty"`
}

ConfigurationResponseWrapper wraps configuration output with consistent status and error fields. Used for create, add-version, and get operations on configurations.

type CreateConfigurationFlags 

type CreateConfigurationFlags struct {
	Name                  string
	AgentType             string
	ManagedEntityType     string
	OperatingSystem       string
	OrganizationID        string
	ConfigurationFilePath string // File content from path
	ConfigurationContent  string // Inline content
}

CreateConfigurationFlags provides typed access to 'create' (configuration) command flags

type CreateDeploymentFlags 

type CreateDeploymentFlags struct {
	FleetID                 string
	Name                    string
	Agent                   []string
	AgentType               string
	AgentVersion            string
	ConfigurationVersionIDs []string
	Description             string
	Tags                    []string
}

CreateDeploymentFlags provides typed access to 'create' (deployment) command flags

type CreateFlags 

type CreateFlags struct {
	Name              string
	ManagedEntityType string
	Description       string
	Product           string
	OrganizationID    string
	OperatingSystem   string
	Tags              []string
}

CreateFlags provides typed access to 'create' command flags

type DeleteConfigurationFlags 

type DeleteConfigurationFlags struct {
	ConfigurationID string
	OrganizationID  string
}

DeleteConfigurationFlags provides typed access to 'delete' (configuration) command flags

type DeleteDeploymentFlags 

type DeleteDeploymentFlags struct {
	DeploymentID string
}

DeleteDeploymentFlags provides typed access to 'delete' (deployment) command flags

type DeleteFlags 

type DeleteFlags struct {
	FleetID  string
	FleetIDs []string
}

DeleteFlags provides typed access to 'delete' command flags

type DeleteVersionFlags 

type DeleteVersionFlags struct {
	VersionID      string
	OrganizationID string
}

DeleteVersionFlags provides typed access to 'delete' (configuration versions) command flags

type DeployFlags 

type DeployFlags struct {
	DeploymentID  string
	RingsToDeploy []string
}

DeployFlags provides typed access to 'deploy' (deployment) command flags

type DeploymentDeleteResponseWrapper 

type DeploymentDeleteResponseWrapper struct {
	Status string `json:"status"`
	Error  string `json:"error"`
	ID     string `json:"id,omitempty"`
}

DeploymentDeleteResponseWrapper wraps deployment delete result with consistent status and error fields.

type DeploymentResponseWrapper 

type DeploymentResponseWrapper struct {
	Status string      `json:"status"`
	Error  string      `json:"error"`
	Result interface{} `json:"result,omitempty"`
}

DeploymentResponseWrapper wraps deployment output with consistent status and error fields. Used for create and update operations on deployments.

type EntityOutput 

type EntityOutput struct {
	ID     string               `json:"id"`
	Name   string               `json:"name"`
	Type   string               `json:"type"`
	Domain string               `json:"domain"`
	Tags   []entities.EntityTag `json:"tags,omitempty"`
}

EntityOutput is a simplified representation of an entity

type ErrorResponse 

type ErrorResponse struct {
	Status string `json:"status"`
	Error  string `json:"error"`
}

ErrorResponse represents an error response with consistent field ordering. Status field comes first, followed by error message.

type FlagDefinition 

type FlagDefinition struct {
	Name        string           `yaml:"name"`                 // Flag name (e.g., "name", "id")
	Type        string           `yaml:"type"`                 // Data type: string, int, bool, stringSlice, stringArray, file
	Required    bool             `yaml:"required"`             // Whether this flag is required
	Default     interface{}      `yaml:"default"`              // Default value if not provided
	Description string           `yaml:"description"`          // Help text for this flag
	Validation  *ValidationRules `yaml:"validation,omitempty"` // Optional validation rules
}

FlagDefinition represents a single flag definition from YAML Flags define the command-line arguments a command accepts

type FlagValues 

type FlagValues struct {
	// contains filtered or unexported fields
}

FlagValues provides dynamic, validated access to flag values This is passed to command handlers and provides type-safe flag access

func (*FlagValues) AddMembers 

func (fv *FlagValues) AddMembers() AddMembersFlags

AddMembers returns typed flags for the 'add' (members) command

func (*FlagValues) AddVersion 

func (fv *FlagValues) AddVersion() (AddVersionFlags, error)

AddVersion returns typed flags for the 'add' (configuration versions) command

func (*FlagValues) Create 

func (fv *FlagValues) Create() CreateFlags

Create returns typed flags for the 'create' command

func (*FlagValues) CreateConfiguration 

func (fv *FlagValues) CreateConfiguration() (CreateConfigurationFlags, error)

CreateConfiguration returns typed flags for the 'create' (configuration) command

func (*FlagValues) CreateDeployment 

func (fv *FlagValues) CreateDeployment() CreateDeploymentFlags

CreateDeployment returns typed flags for the 'create' (deployment) command

func (*FlagValues) Delete 

func (fv *FlagValues) Delete() DeleteFlags

Delete returns typed flags for the 'delete' command

func (*FlagValues) DeleteConfiguration 

func (fv *FlagValues) DeleteConfiguration() DeleteConfigurationFlags

DeleteConfiguration returns typed flags for the 'delete' (configuration) command

func (*FlagValues) DeleteDeployment 

func (fv *FlagValues) DeleteDeployment() DeleteDeploymentFlags

DeleteDeployment returns typed flags for the 'delete' (deployment) command

func (*FlagValues) DeleteVersion 

func (fv *FlagValues) DeleteVersion() DeleteVersionFlags

DeleteVersion returns typed flags for the 'delete' (configuration versions) command

func (*FlagValues) Deploy 

func (fv *FlagValues) Deploy() DeployFlags

Deploy returns typed flags for the 'deploy' (deployment) command

func (*FlagValues) Get 

func (fv *FlagValues) Get() GetFlags

Get returns typed flags for the 'get' command

func (*FlagValues) GetBool 

func (fv *FlagValues) GetBool(name string) bool

GetBool retrieves a validated bool flag value by name Values are cached after first retrieval for performance

Parameters:

  • name: The flag name

Returns:

  • The bool value of the flag

func (*FlagValues) GetConfiguration 

func (fv *FlagValues) GetConfiguration() GetConfigurationFlags

GetConfiguration returns typed flags for the 'get' (configuration) command

func (*FlagValues) GetFile 

func (fv *FlagValues) GetFile(name string) (string, error)

GetFile retrieves file content from a file path (strict file reading only) This method requires a valid file path and errors if the file doesn't exist. For inline content, use separate -content flags with GetString instead. Values are cached after first retrieval for performance

Parameters:

  • name: The flag name

Returns:

  • The file content
  • Error if file doesn't exist or reading fails

Example: 

// User must provide a valid file path:
// --configuration-file-path ./config.json  (reads file)
// For inline content, use --configuration-content flag instead

func (*FlagValues) GetInt 

func (fv *FlagValues) GetInt(name string) int

GetInt retrieves a validated int flag value by name Values are cached after first retrieval for performance

Parameters:

  • name: The flag name

Returns:

  • The int value of the flag

func (*FlagValues) GetManaged 

func (fv *FlagValues) GetManaged() GetManagedFlags

GetManaged returns typed flags for the 'get-managed' (entities) command

func (*FlagValues) GetString 

func (fv *FlagValues) GetString(name string) string

GetString retrieves a validated string flag value by name Values are cached after first retrieval for performance

Parameters:

  • name: The flag name

Returns:

  • The string value of the flag

func (*FlagValues) GetStringArray 

func (fv *FlagValues) GetStringArray(name string) []string

GetStringArray retrieves a validated string array flag value by name Values are cached after first retrieval for performance Note: stringArray type does NOT auto-split on commas (only splits when flag is repeated)

Parameters:

  • name: The flag name

Returns:

  • The string array value of the flag

func (*FlagValues) GetStringSlice 

func (fv *FlagValues) GetStringSlice(name string) []string

GetStringSlice retrieves a validated string slice flag value by name Values are cached after first retrieval for performance Note: stringSlice type auto-splits on commas

Parameters:

  • name: The flag name

Returns:

  • The string slice value of the flag

func (*FlagValues) GetUnassigned 

func (fv *FlagValues) GetUnassigned() GetUnassignedFlags

GetUnassigned returns typed flags for the 'get-unassigned' (entities) command

func (*FlagValues) GetVersions 

func (fv *FlagValues) GetVersions() GetVersionsFlags

GetVersions returns typed flags for the 'list' (configuration versions) command

func (*FlagValues) Has 

func (fv *FlagValues) Has(name string) bool

Has checks if a flag was explicitly provided by the user This is useful for distinguishing between a flag being omitted vs set to default value

Parameters:

  • name: The flag name

Returns:

  • true if the flag was provided, false otherwise

func (*FlagValues) ListMembers 

func (fv *FlagValues) ListMembers() ListMembersFlags

ListMembers returns typed flags for the 'list' (members) command

func (*FlagValues) RemoveMembers 

func (fv *FlagValues) RemoveMembers() RemoveMembersFlags

RemoveMembers returns typed flags for the 'remove' (members) command

func (*FlagValues) Search 

func (fv *FlagValues) Search() SearchFlags

Search returns typed flags for the 'search' command

func (*FlagValues) Update 

func (fv *FlagValues) Update() UpdateFlags

Update returns typed flags for the 'update' command

func (*FlagValues) UpdateDeployment 

func (fv *FlagValues) UpdateDeployment() UpdateDeploymentFlags

UpdateDeployment returns typed flags for the 'update' (deployment) command

type FleetDeleteResponseWrapper 

type FleetDeleteResponseWrapper struct {
	Status string `json:"status"`
	Error  string `json:"error"`
	ID     string `json:"id,omitempty"`
}

FleetDeleteResponseWrapper wraps delete result with consistent status and error fields.

type FleetEntityOutput 

type FleetEntityOutput struct {
	ID                string                                    `json:"id"`
	Name              string                                    `json:"name"`
	Type              string                                    `json:"type,omitempty"`
	ManagedEntityType string                                    `json:"managedEntityType,omitempty"`
	OperatingSystem   *fleetcontrol.FleetControlOperatingSystem `json:"operatingSystem,omitempty"`
	Scope             fleetcontrol.FleetControlScopedReference  `json:"scope,omitempty"`
	Tags              []fleetcontrol.FleetControlTag            `json:"tags,omitempty"`
	Product           []string                                  `json:"product,omitempty"`
	Description       string                                    `json:"description,omitempty"`
	CreatedAt         int64                                     `json:"createdAt,omitempty"`
	UpdatedAt         int64                                     `json:"updatedAt,omitempty"`
}

FleetEntityOutput is a filtered representation of a fleet entity containing only user-relevant fields. This removes verbose metadata and internal structures that aren't useful for command output.

func FilterFleetEntity 

func FilterFleetEntity(entity fleetcontrol.FleetControlFleetEntityResult) *FleetEntityOutput

FilterFleetEntity creates a filtered output from a fleet entity, removing verbose fields. This keeps only the fields that correspond to command flags or essential metadata.

Parameters:

  • entity: The fleet entity from the API response

Returns:

  • Filtered fleet entity output

func FilterFleetEntityFromEntityManagement 

func FilterFleetEntityFromEntityManagement(entity fleetcontrol.EntityManagementFleetEntity, showTags bool) *FleetEntityOutput

FilterFleetEntityFromEntityManagement creates a filtered output from an EntityManagementFleetEntity. This is used for the get and search commands which use the EntityManagement API.

Parameters:

  • entity: The fleet entity from EntityManagement API
  • showTags: Whether to include tags in the output

Returns:

  • Filtered fleet entity output

type FleetListResponseWrapper 

type FleetListResponseWrapper struct {
	Status string              `json:"status"`
	Error  string              `json:"error"`
	Fleets []FleetEntityOutput `json:"fleets,omitempty"`
}

FleetListResponseWrapper wraps a list of fleet entities with consistent status and error fields.

type FleetMemberEntityWithoutTags 

type FleetMemberEntityWithoutTags struct {
	ID       string                                   `json:"id"`
	Metadata fleetcontrol.FleetControlMetadata        `json:"metadata"`
	Name     string                                   `json:"name"`
	Scope    fleetcontrol.FleetControlScopedReference `json:"scope"`
	Type     string                                   `json:"type"`
}

FleetMemberEntityWithoutTags is a filtered version of FleetControlFleetMemberEntityResult that excludes the Tags field, used when --include-tags is false

type FleetMembersResultWithoutTags 

type FleetMembersResultWithoutTags struct {
	Items      []FleetMemberEntityWithoutTags `json:"items"`
	NextCursor string                         `json:"nextCursor,omitempty"`
}

FleetMembersResultWithoutTags is the result structure without tags

type FleetResponseWrapper 

type FleetResponseWrapper struct {
	Status            string                                    `json:"status"`
	Error             string                                    `json:"error"`
	ID                string                                    `json:"id,omitempty"`
	Name              string                                    `json:"name,omitempty"`
	Type              string                                    `json:"type,omitempty"`
	ManagedEntityType string                                    `json:"managedEntityType,omitempty"`
	OperatingSystem   *fleetcontrol.FleetControlOperatingSystem `json:"operatingSystem,omitempty"`
	Scope             *fleetcontrol.FleetControlScopedReference `json:"scope,omitempty"`
	Tags              []fleetcontrol.FleetControlTag            `json:"tags,omitempty"`
	Product           []string                                  `json:"product,omitempty"`
	Description       string                                    `json:"description,omitempty"`
	CreatedAt         int64                                     `json:"createdAt,omitempty"`
	UpdatedAt         int64                                     `json:"updatedAt,omitempty"`
}

FleetResponseWrapper wraps fleet entity output with consistent status and error fields. Used to provide a uniform response structure across all fleet management commands.

type GetConfigurationFlags 

type GetConfigurationFlags struct {
	ConfigurationID string
	OrganizationID  string
	Mode            string
	Version         int
}

GetConfigurationFlags provides typed access to 'get' (configuration) command flags

type GetFlags 

type GetFlags struct {
	FleetID string
}

GetFlags provides typed access to 'get' command flags

type GetManagedFlags 

type GetManagedFlags struct {
	EntityType  string
	Limit       int
	IncludeTags bool
}

GetManagedFlags provides typed access to 'get-managed' (entities) command flags

type GetUnassignedFlags 

type GetUnassignedFlags struct {
	EntityType  string
	Limit       int
	IncludeTags bool
}

GetUnassignedFlags provides typed access to 'get-unassigned' (entities) command flags

type GetVersionsFlags 

type GetVersionsFlags struct {
	ConfigurationID string
	OrganizationID  string
}

GetVersionsFlags provides typed access to 'list' (configuration versions) command flags

type ListMembersFlags 

type ListMembersFlags struct {
	FleetID  string
	Ring     string
	ShowTags bool
}

ListMembersFlags provides typed access to 'list' (members) command flags

type MemberResponseWrapper 

type MemberResponseWrapper struct {
	Status string      `json:"status"`
	Error  string      `json:"error"`
	Result interface{} `json:"result,omitempty"`
}

MemberResponseWrapper wraps member operation output with consistent status and error fields. Used for add-members and remove-members operations.

type RemoveMembersFlags 

type RemoveMembersFlags struct {
	FleetID   string
	Ring      string
	EntityIDs []string
}

RemoveMembersFlags provides typed access to 'remove' (members) command flags

type SearchFlags 

type SearchFlags struct {
	NameEquals   string
	NameContains string
	ShowTags     bool
}

SearchFlags provides typed access to 'search' command flags

type UpdateDeploymentFlags 

type UpdateDeploymentFlags struct {
	DeploymentID            string
	Name                    string
	Description             string
	Agent                   []string
	ConfigurationVersionIDs []string
	Tags                    []string
}

UpdateDeploymentFlags provides typed access to 'update' (deployment) command flags

type UpdateFlags 

type UpdateFlags struct {
	ID          string
	Name        string
	Description string
	Tags        []string
}

UpdateFlags provides typed access to 'update' command flags

type ValidationRules 

type ValidationRules struct {
	AllowedValues   []string `yaml:"allowed_values,omitempty"`   // List of acceptable values
	CaseInsensitive bool     `yaml:"case_insensitive,omitempty"` // Whether to ignore case when validating
}

ValidationRules defines validation constraints for a flag These rules are enforced by the framework before the command handler runs

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.