karrio-cli 2026.1.14
Command line interface for Karrio
License: MIT
Requires Python: >=3.11

# Karrio CLI Tools

This folder contains CLI tools for the Karrio project.

## Codegen

The `codegen` command provides utilities for code generation, particularly for transforming JSON schemas into Python code using jstruct.

### Transform

The `transform` command converts Python code generated by quicktype (using dataclasses) into code that uses attrs and jstruct decorators.

```bash
# Transform from stdin to stdout
cat input.py | karrio codegen transform > output.py

# Transform from file to file
karrio codegen transform input.py output.py

# Transform from file to stdout
karrio codegen transform input.py

# Disable appending 'Type' to class names
karrio codegen transform input.py output.py --no-append-type-suffix
```

The transform command makes the following changes:
- Replaces `from dataclasses import dataclass` with explicit imports: `import attr`, `import jstruct`, `import typing`
- Removes any `from typing import ...` lines entirely
- Replaces `@dataclass` with `@attr.s(auto_attribs=True)`
- Appends 'Type' to all class names (unless they already end with 'Type') by default
- Replaces complex type annotations with jstruct equivalents
- Ensures there are no duplicate import statements

### Generate

The `generate` command generates Python code with jstruct from a JSON schema file using quicktype.

```bash
# Generate Python code with jstruct from a JSON schema
karrio codegen generate --src=schema.json --out=output.py

# Specify Python version
karrio codegen generate --src=schema.json --out=output.py --python-version=3.8

# Generate without --just-types
karrio codegen generate --src=schema.json --out=output.py --just-types=false

# Disable appending 'Type' to class names
karrio codegen generate --src=schema.json --out=output.py --no-append-type-suffix
```

### Create Tree

The `create-tree` command generates a Python code tree from a class definition. It's useful for visualizing the structure of complex nested objects and generating initialization code templates.

```bash
# Generate a tree for a class
karrio codegen create-tree --module=karrio.schemas.allied_express.label_request --class-name=LabelRequest

# Generate a tree with a module alias
karrio codegen create-tree --module=karrio.schemas.allied_express.label_request --class-name=LabelRequest --module-alias=allied
```

Example output:
```python
LabelRequestType(
    bookedBy=None,
    account=None,
    instructions=None,
    itemCount=None,
    items=[
        ItemType(
            dangerous=None,
            height=None,
            itemCount=None,
            length=None,
            volume=None,
            weight=None,
            width=None,
        )
    ],
    jobStopsP=JobStopsType(
        companyName=None,
        contact=None,
        emailAddress=None,
        geographicAddress=GeographicAddressType(
            address1=None,
            address2=None,
            country=None,
            postCode=None,
            state=None,
            suburb=None,
        ),
        phoneNumber=None,
    ),
    jobStopsD=JobStopsType(...),
    referenceNumbers=[],
    serviceLevel=None,
    volume=None,
    weight=None,
)
```

## Migrating carrier connector generate scripts

To migrate carrier connector generate scripts to use the new codegen command, run:

```bash
python karrio/modules/cli/commands/migrate_generate_scripts.py /path/to/karrio/workspace
```

This will update all generate scripts in the carrier connectors to use the new karrio codegen command.

## JStruct Overview

JStruct is a Python library for nested object models that offers serialization and deserialization into Python dictionaries. It leverages the `attrs` library to define structs without boilerplate.

Here's an example of the transformed code:

```python
import attr
import jstruct
import typing

@attr.s(auto_attribs=True)
class PersonType:
    first_name: typing.Optional[str] = None
    last_name: typing.Optional[str] = None

@attr.s(auto_attribs=True)
class RoleModelsType:
    scientists: typing.Optional[typing.List[PersonType]] = jstruct.JList[PersonType]
```

For more information, see the [JStruct README](https://github.com/karrioapi/jstruct/blob/main/README.md).