CLI (Command Line Interface) Documentation

PyArchInit-Mini provides a rich command-line interface built with Click and Rich libraries, offering an interactive terminal experience for managing archaeological data.

Quick Start

Starting the CLI

To start the interactive CLI:

pyarchinit-mini

# Welcome to PyArchInit-Mini CLI!
# Type 'help' to see available commands or 'exit' to quit.
# pyarchinit>

Available Commands

Type help in the CLI to see all available commands:

pyarchinit> help

Available commands:
- list-sites      : List all archaeological sites
- create-site     : Create a new site
- list-us         : List stratigraphic units
- create-us       : Create a new US
- list-inventory  : List inventory items
- create-inventory: Create a new inventory item
- search          : Search across all data
- export          : Export data to various formats
- import          : Import data from CSV/Excel
- harris-matrix   : Generate Harris Matrix
- stats           : Show database statistics
- help            : Show this help message
- exit            : Exit the CLI

Command Structure

Basic Command Syntax

Commands follow a consistent pattern:

pyarchinit> command-name [options] [arguments]

Examples:

pyarchinit> list-sites
pyarchinit> list-sites --limit 10
pyarchinit> search --type site --query "Pompei"
pyarchinit> export --format excel --output sites.xlsx

Interactive Mode Features

The CLI provides several interactive features:

Auto-completion: Press TAB to auto-complete commands
Command history: Use UP/DOWN arrows to navigate history
Color output: Important information highlighted in colors
Progress bars: Visual feedback for long operations
Tables: Data displayed in formatted tables
Prompts: Interactive prompts for required information

Site Management Commands

list-sites

List all archaeological sites with optional filtering:

pyarchinit> list-sites [OPTIONS]

Options:
  --limit INTEGER     Maximum number of sites to display [default: 20]
  --offset INTEGER    Number of sites to skip [default: 0]
  --sort-by TEXT      Field to sort by [default: site_name]
  --search TEXT       Search sites by name or location

Example output:

┏━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
┃ ID ┃ Site Name     ┃ Location   ┃ Comune    ┃ Definition         ┃
┡━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
│ 1  │ Pompei        │ Campania   │ Pompei    │ Ancient Roman city │
│ 2  │ Herculaneum   │ Campania   │ Ercolano  │ Roman settlement   │
└────┴───────────────┴────────────┴───────────┴────────────────────┘

create-site

Create a new archaeological site interactively:

pyarchinit> create-site

The command will prompt for:

Site name (required)
Location/Nation
Region
Comune (municipality)
Province
Site definition (Italian)
Site definition (English)

Example:

pyarchinit> create-site

Creating new archaeological site...

Site name: Villa Adriana
Location (Nation) [Italia]:
Region: Lazio
Comune: Tivoli
Province: Roma
Site definition (IT): Villa imperiale romana
Site definition (EN): Roman imperial villa

✓ Site 'Villa Adriana' created successfully!

update-site

Update an existing site:

pyarchinit> update-site SITE_NAME

Options:
  --name TEXT         New site name
  --location TEXT     New location
  --region TEXT       New region
  --comune TEXT       New comune
  --definition TEXT   New definition

delete-site

Delete a site (with confirmation):

pyarchinit> delete-site SITE_NAME

⚠️  Are you sure you want to delete site 'SITE_NAME'? [y/N]:

Stratigraphic Units (US) Commands

list-us

List stratigraphic units with filters:

pyarchinit> list-us [OPTIONS]

Options:
  --site TEXT         Filter by site name
  --area TEXT         Filter by area
  --limit INTEGER     Maximum number of US to display
  --sort-by TEXT      Sort by field (us, area, d_stratigrafica)

create-us

Create a new stratigraphic unit:

pyarchinit> create-us

Interactive prompts will guide through all 49 US fields organized in tabs:

Basic Information (site, area, US number)
Stratigraphic Data
Characteristics
Dating Information
Documentation
Relationships

search-us

Search US by various criteria:

pyarchinit> search-us [OPTIONS]

Options:
  --site TEXT         Site name
  --area TEXT         Area
  --us INTEGER        US number
  --type TEXT         Unit type (US, USM, USD, USV)
  --period TEXT       Chronological period
  --definition TEXT   Search in definitions

Inventory Commands

list-inventory

List inventory items:

pyarchinit> list-inventory [OPTIONS]

Options:
  --site TEXT         Filter by site
  --type TEXT         Filter by artifact type
  --limit INTEGER     Maximum items to display
  --material TEXT     Filter by material

create-inventory

Create new inventory item (37 fields):

pyarchinit> create-inventory

Prompts for all inventory fields including: - Basic data (number, type, material) - Measurements - Conservation state - Dating - Bibliography - ICCD thesaurus terms

Export/Import Commands

The CLI includes dedicated export/import functionality:

Export Commands

# Export sites to Excel
pyarchinit-export-import export-sites -f excel -o sites.xlsx

# Export US to CSV for specific site
pyarchinit-export-import export-us -f csv -s "Pompei" -o pompei_us.csv

# Export inventory to Excel
pyarchinit-export-import export-inventario -f excel -o inventory.xlsx

Import Commands

# Import sites from CSV
pyarchinit-export-import import-sites sites.csv

# Import US with duplicate handling
pyarchinit-export-import import-us --skip-duplicates us_data.csv

# Import inventory without skipping duplicates
pyarchinit-export-import import-inventario --no-skip-duplicates inventory.csv

Harris Matrix Commands

generate-matrix

Generate Harris Matrix for a site:

pyarchinit> harris-matrix SITE_NAME [OPTIONS]

Options:
  --format TEXT       Output format (png, pdf, svg) [default: png]
  --output TEXT       Output filename
  --dpi INTEGER       DPI for raster formats [default: 300]
  --grouping TEXT     Grouping mode (period_area, period, area, none)

Example:

pyarchinit> harris-matrix "Pompei" --format pdf --output pompei_matrix.pdf

Generating Harris Matrix for site 'Pompei'...
✓ Found 127 stratigraphic units
✓ Processing 245 relationships
✓ Matrix generated successfully: pompei_matrix.pdf

validate-stratigraphy

Check for stratigraphic inconsistencies:

pyarchinit> validate-stratigraphy SITE_NAME

Validating stratigraphy for site 'Pompei'...

⚠️  Found 3 issues:

1. Missing reciprocal relationship:
   US 1001 covers US 1002, but US 1002 doesn't list "covered by 1001"

2. Stratigraphic paradox detected:
   US 2001 → US 2002 → US 2003 → US 2001 (circular reference)

3. Temporal inconsistency:
   US 3001 (Medieval) covers US 3002 (Modern)

GraphML Export Commands

The CLI includes a dedicated GraphML converter:

# Convert DOT file to GraphML
pyarchinit-graphml convert input.dot output.graphml -t "Site Title"

# Convert with custom template
pyarchinit-graphml convert input.dot output.graphml \
  -t "Pompei Excavation" \
  --template my_template.graphml

# Batch conversion
pyarchinit-graphml batch input_dir/ output_dir/ -t "Project Name"

# Get default template
pyarchinit-graphml template -o EM_palette.graphml

Search Functionality

Global Search

Search across all data types:

pyarchinit> search QUERY [OPTIONS]

Options:
  --type TEXT         Limit to type (site, us, inventory)
  --limit INTEGER     Maximum results per type
  --exact             Exact match only

Example:

pyarchinit> search "romano" --limit 5

Search results for "romano":

📍 Sites (2 results):
- Pompei: Ancient Roman city
- Ostia Antica: Roman port city

📋 Stratigraphic Units (5 results):
- US 1001: Strato romano imperiale
- US 1045: Pavimento romano
- US 2003: Muro romano
- US 3021: Deposito romano
- US 4001: Crollo strutture romane

📦 Inventory (3 results):
- INV001: Ceramica romana
- INV045: Moneta romana
- INV123: Tegola romana

Advanced Search

Use filters for precise searching:

pyarchinit> advanced-search

Select search type:
1. Sites
2. Stratigraphic Units
3. Inventory

Choice: 2

US Search Criteria:
- Site name (optional): Pompei
- Area (optional): A
- US type (optional): US
- Period (optional): Romano
- Date range (optional):
- Text search in definitions: villa

Statistics Command

View database statistics:

pyarchinit> stats

📊 PyArchInit-Mini Database Statistics

Overview:
├── Total Sites: 12
├── Total US: 1,247
├── Total Inventory Items: 3,456
└── Total Relationships: 2,891

By Site:
├── Pompei: 523 US, 1,234 items
├── Herculaneum: 312 US, 876 items
└── Ostia: 412 US, 1,346 items

By Period:
├── Romano: 45%
├── Medievale: 23%
├── Moderno: 18%
└── Contemporaneo: 14%

Database Commands

db-info

Show database connection information:

pyarchinit> db-info

Database Information:
├── Type: PostgreSQL
├── Host: localhost:5432
├── Database: pyarchinit
├── User: pyarchinit_user
└── Tables: 15

db-backup

Create database backup:

pyarchinit> db-backup [OPTIONS]

Options:
  --output TEXT       Backup filename
  --compress          Compress backup

Configuration

The CLI uses the same configuration as other interfaces:

~/.pyarchinit_mini/config/config.yaml

CLI-specific settings:

cli:
  colors: true          # Enable colored output
  page_size: 20         # Default pagination size
  date_format: "%Y-%m-%d"
  export_format: excel  # Default export format
  confirm_delete: true  # Require confirmation for deletions

Environment Variables

# Disable colors
export PYARCHINIT_CLI_NO_COLOR=1

# Set default export directory
export PYARCHINIT_EXPORT_DIR=/path/to/exports

# Skip confirmation prompts
export PYARCHINIT_CLI_YES=1

Keyboard Shortcuts

While in the CLI:

Ctrl+C: Cancel current operation
Ctrl+D: Exit CLI (same as ‘exit’)
TAB: Auto-complete commands
↑/↓: Navigate command history
Ctrl+R: Search command history
Ctrl+L: Clear screen

Tips and Tricks

Command Aliases

Create shorter aliases for common commands:

pyarchinit> alias ls list-sites
pyarchinit> alias lus list-us

Output Redirection

Save command output to file:

pyarchinit> list-sites > sites.txt
pyarchinit> list-us --site "Pompei" > pompei_us.txt

Batch Operations

Use the CLI in scripts:

echo "list-sites
stats
exit" | pyarchinit-mini > report.txt

JSON Output

Get machine-readable output:
```
pyarchinit> list-sites --format json
```

Quiet Mode

Suppress interactive prompts:

pyarchinit> create-site --quiet \
  --name "Test Site" \
  --region "Lazio" \
  --comune "Roma"

Error Handling

The CLI provides clear error messages:

pyarchinit> create-site

Site name: Pompei

❌ Error: Site 'Pompei' already exists!

Try:
- Use a different site name
- Run 'update-site Pompei' to modify existing site
- Run 'list-sites' to see all sites

Integration Examples

Shell Script Integration

#!/bin/bash
# backup_archaeological_data.sh

DATE=$(date +%Y%m%d)
EXPORT_DIR="./backups/$DATE"

mkdir -p $EXPORT_DIR

# Export all data
pyarchinit-export-import export-sites -f excel -o "$EXPORT_DIR/sites.xlsx"
pyarchinit-export-import export-us -f excel -o "$EXPORT_DIR/us.xlsx"
pyarchinit-export-import export-inventario -f excel -o "$EXPORT_DIR/inventory.xlsx"

# Generate Harris matrices for all sites
echo "list-sites --format json" | pyarchinit-mini | \
jq -r '.[] | .site_name' | \
while read site; do
  echo "Generating matrix for $site..."
  pyarchinit-mini harris-matrix "$site" \
    --format pdf \
    --output "$EXPORT_DIR/${site// /_}_matrix.pdf"
done

Python Integration

import subprocess
import json

def get_sites():
    """Get all sites from CLI"""
    result = subprocess.run(
        ['pyarchinit-mini', 'list-sites', '--format', 'json'],
        capture_output=True,
        text=True
    )
    return json.loads(result.stdout)

def create_site_batch(sites_data):
    """Create multiple sites"""
    for site in sites_data:
        cmd = [
            'pyarchinit-mini', 'create-site', '--quiet',
            '--name', site['name'],
            '--region', site['region'],
            '--comune', site['comune']
        ]
        subprocess.run(cmd)

# Example usage
sites = get_sites()
print(f"Found {len(sites)} sites")