Metadata-Version: 2.3
Name: fct-kiwi
Version: 1.0.2
Summary: Balena fleet management
License: MIT
Keywords: balena,fleet control
Author: Juan Pablo Castillo
Author-email: jpc.2@outlook.com
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: balena-sdk (>=15.1.2,<16.0.0)
Requires-Dist: click (>=8.1.8,<9.0.0)
Requires-Dist: google-auth (>=2.38.0,<3.0.0)
Requires-Dist: google-cloud-tasks (>=2.19.1,<3.0.0)
Requires-Dist: gspread (>=6.2.0,<7.0.0)
Requires-Dist: python-dotenv (>=1.1.0,<2.0.0)
Requires-Dist: pytz (>=2025.1,<2026.0)
Requires-Dist: requests (>=2.32.3,<3.0.0)
Project-URL: Repository, https://github.com/gokiwibot/fct-package
Description-Content-Type: text/markdown

# FCT-Kiwi

A command-line tool for Balena device configuration management, allowing you to easily change, clone, purge, retrieve, and manage variables across devices and fleets.

## Table of Contents

- [FCT-Kiwi](#fct-kiwi)
  - [Table of Contents](#table-of-contents)
  - [Installation](#installation)
  - [Authentication](#authentication)
  - [Commands](#commands)
    - [Usage in other scripts](#usage-in-other-scripts)
    - [Change](#change)
    - [Clone](#clone)
    - [Purge](#purge)
    - [Get](#get)
    - [Delete](#delete)
    - [Move](#move)
    - [Schedule](#schedule)
    - [Initialize](#initialize)
  - [File Format](#file-format)
  - [Error Handling](#error-handling)
  - [Dependencies](#dependencies)
  - [Author](#author)

## Installation

```bash
pip install fct-kiwi
```

## Authentication

To use this tool, you need to set up your Balena API key as an environment variable:

1. Create a `.env` file in the same directory as the script
2. Add your Balena API key: `BALENA_API_KEY=your_api_key_here`

## Commands

### Usage in other scripts

To use this packages functionality in other scripts simply import the functions you need from the following list.

```python
from fleet_control import clone, change, etc...
```

### Change

Change or create specified variable(s) to target device(s).

```bash
# Basic usage
fct change 'NODE_WEATHER_DEBUG=0=*' 4D163 4D164

# Change multiple variables
fct change 'NODE_WEATHER_DEBUG=0=* ANOTHER_VAR=value=service' 4D163 4D164

# Target a fleet
fct change 'NODE_WEATHER_DEBUG=0=*' Staging4_x

# Use a file containing variables
fct change --file variables.txt '' 4D163 4D164
```

### Clone

Clone configuration from a source device or fleet to target device(s).

```bash
# Clone from one device to others
fct clone 4E288 4D163 4D164

# Clone from a fleet to a device
fct clone Staging4_x 4D163

# Clone from a fleet to another fleet
fct clone Staging4_x fleet_name

# Clone with exclusions
fct clone --exclude "VAR1 VAR2" 4E288 4D163 4D164
```

### Purge

Purge all custom variables in target device(s).

```bash
# Purge all custom variables from devices
fct purge 4E288 4D163 4D164

# Purge with exclusions
fct purge --exclude "VAR1 VAR2" 4E288 4D163 4D164
```

### Get

Fetch variable value(s) for a device.

```bash
# Get a specific variable
fct get 4E288 UAVCAN_CHASSIS_CURRENT_T2

# Get all custom variables
fct get 4E288 --custom

# Get all variables (device + fleet)
fct get 4E288 --all-vars

# Save variables to a file
fct get 4E288 --output result.json
```

### Delete

Delete the overwritten value for specified variable(s) on the target device(s).

```bash
# Delete a variable
fct delete 'NODE_WEATHER_DEBUG=0=*' 4D163 4D164

# Delete multiple variables
fct delete 'VAR1=value=service VAR2=value=*' 4D163 4D164

# Delete variables from a file
fct delete --file variables.txt '' 4D163 4D164
```

### Move

Move target(s) from its current fleet to a specified fleet.

```bash
# Move devices to a new fleet
fct move Staging4_x 4E288 4D163 4D164

# Move keeping custom device variables
fct move --keep-vars Staging4_x 4E288 4D163 4D164

# Move keeping custom device and service variables
fct move --keep-service-vars Staging4_x 4E288 4D163 4D164

# Move with cloning (keep custom and previous fleet variables)
fct move --clone Staging4_x 4E288 4D163 4D164

# Move and pin to specific release
fct move --semver "1.3.11+rev87" Staging4_x 4E288 4D163 4D164
```

### Schedule

Schedule variable changes to be applied at a specific time.

```bash
# Schedule a change for tomorrow at 3 AM (default)
fct schedule 'WEATHER_NODE_DEBUG=0=main' 4B058 4D163

# Schedule with a specific date and time
fct schedule --date '2025-02-25 12:06:00' 'WEATHER_NODE_DEBUG=0=main' 4B058 4D163

# Schedule with a file containing variables
fct schedule --file vars.json --date '2025-02-25 12:06:00' '' 4B058

# Schedule with different timezone
fct schedule --tz 'America/New_York' 'WEATHER_NODE_DEBUG=0=main' 4B058 4D163
```

### Initialize

Initialize a target device with previous device tags, remove old device, delete default config variables, and move to specified fleet.

```bash
# Initialize a device and move it to a fleet
fct initialize Staging4_x 4E288
```

## File Format

When using the `--file` option, the file should contain JSON formatted variables:

```json
{
  "env_vars": {
      "VAR1_NAME": "VAR1_VALUE",
      "VAR2_NAME": 2
  },
  "service_vars": {
      "main": {
        "SERVICE_VAR1_NAME": "SERVICE_VAR1_VALUE",
        "SERVICE_VAR2_NAME": "SERVICE_VAR2_VALUE"
      }
  }
}
```

For variable scheduling:

```json
{
    "purge": false,
    "Target": [
        {
            "is_fleet": "TARGET1_TYPE",
            "name": "TARGET1_NAME"
        },
        {
            "is_fleet": "TARGET2_TYPE",
            "name": "TARGET2_NAME"
        }
    ],
    "variables": [
        {
            "name": "VAR1_NAME",
            "value": "VAR1_VALUE",
            "service": "VAR1_TYPE"
        },
                {
            "name": "VAR2_NAME",
            "value": "VAR2_VALUE",
            "service": "VAR2_TYPE"
        },
    ]
}
```

## Error Handling

The tool will return appropriate error messages if:

- The Balena API key is not set
- No variables are provided when required
- Target devices or fleets cannot be found
- API requests fail

## Dependencies

- balena-sdk
- click
- python-dotenv

## Author

Juan Pablo Castillo - <juan.castillo@kiwibot.com>

