Run Keboola component locally with test data and display results
Executes Keboola components locally with test data and displays results.
/plugin marketplace add keboola/ai-kit/plugin install component-developer@keboola-claude-kitconfig-fileRun your Keboola component locally with test configuration and automatically display results.
data/config.json existsKBC_DATADIR=data# Run with default data/config.json
/run
# Run with specific config file
/run data/config-test.json
# Run with custom data directory
/run --datadir=test-data
# Run with verbose output
/run --verbose
Check that we're in a component directory:
# Check for component files
test -f src/component.py || {
echo "Error: Not in a component directory (src/component.py not found)"
exit 1
}
# Check for pyproject.toml or requirements.txt
test -f pyproject.toml || test -f requirements.txt || {
echo "Error: No pyproject.toml or requirements.txt found"
exit 1
}
Extract config file from arguments or use default:
# Parse arguments
CONFIG_FILE="data/config.json"
DATA_DIR="data"
VERBOSE=false
# If $ARGUMENTS contains a path, use it
if [[ "$ARGUMENTS" == *.json ]]; then
CONFIG_FILE="$ARGUMENTS"
DATA_DIR=$(dirname "$CONFIG_FILE")
fi
# Check if --datadir specified
if [[ "$ARGUMENTS" == *"--datadir="* ]]; then
DATA_DIR=$(echo "$ARGUMENTS" | grep -oP '(?<=--datadir=)[^ ]+')
CONFIG_FILE="$DATA_DIR/config.json"
fi
# Check if config file exists
test -f "$CONFIG_FILE" || {
echo "Error: Config file not found: $CONFIG_FILE"
echo ""
echo "Create it first:"
echo " mkdir -p $DATA_DIR"
echo " cat > $CONFIG_FILE << 'EOF'"
echo ' {'
echo ' "parameters": {'
echo ' "debug": true'
echo ' }'
echo ' }'
echo ' EOF'
exit 1
}
Ensure all required Keboola directories exist:
# Create standard Keboola directory structure
mkdir -p "$DATA_DIR/in/tables"
mkdir -p "$DATA_DIR/in/files"
mkdir -p "$DATA_DIR/out/tables"
mkdir -p "$DATA_DIR/out/files"
mkdir -p "$DATA_DIR/out/state"
echo "✓ Data directory structure ready: $DATA_DIR"
Ensure dependencies are installed:
# Check if using uv (modern, faster)
if command -v uv &> /dev/null && test -f pyproject.toml; then
echo "📦 Checking dependencies (uv)..."
uv sync --quiet || {
echo "⚠ Dependencies need to be installed"
echo "Run: uv sync"
exit 1
}
RUN_CMD="uv run python"
elif command -v python3 &> /dev/null; then
echo "📦 Using python3..."
RUN_CMD="python3"
else
echo "Error: No Python found (tried: uv, python3)"
exit 1
fi
Execute the component with proper environment:
# Set environment
export KBC_DATADIR="$DATA_DIR"
# Show run info
echo ""
echo "🚀 Running component..."
echo " Config: $CONFIG_FILE"
echo " Data dir: $DATA_DIR"
echo " Command: $RUN_CMD src/component.py"
echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
# Run component and capture exit code
START_TIME=$(date +%s)
if $RUN_CMD src/component.py; then
EXIT_CODE=0
else
EXIT_CODE=$?
fi
END_TIME=$(date +%s)
DURATION=$((END_TIME - START_TIME))
echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
Show execution results based on exit code:
if [ $EXIT_CODE -eq 0 ]; then
echo "✅ Component completed successfully ($DURATION seconds)"
echo ""
# Show output tables
if [ -d "$DATA_DIR/out/tables" ] && [ "$(ls -A $DATA_DIR/out/tables 2>/dev/null)" ]; then
echo "📊 Output tables:"
for table in "$DATA_DIR/out/tables"/*.csv; do
if [ -f "$table" ]; then
filename=$(basename "$table")
lines=$(wc -l < "$table" | xargs)
size=$(du -h "$table" | cut -f1)
echo " • $filename ($lines lines, $size)"
# Show first few rows if verbose
if [[ "$ARGUMENTS" == *"--verbose"* ]]; then
echo ""
head -n 5 "$table" | column -t -s ',' || head -n 5 "$table"
echo " ..."
echo ""
fi
fi
done
echo ""
fi
# Show output files
if [ -d "$DATA_DIR/out/files" ] && [ "$(ls -A $DATA_DIR/out/files 2>/dev/null)" ]; then
echo "📁 Output files:"
for file in "$DATA_DIR/out/files"/*; do
if [ -f "$file" ]; then
filename=$(basename "$file")
size=$(du -h "$file" | cut -f1)
echo " • $filename ($size)"
fi
done
echo ""
fi
# Show state
if [ -f "$DATA_DIR/out/state.json" ]; then
echo "💾 State file created:"
echo " $(du -h $DATA_DIR/out/state.json | cut -f1) - $DATA_DIR/out/state.json"
if [[ "$ARGUMENTS" == *"--verbose"* ]]; then
echo ""
cat "$DATA_DIR/out/state.json" | python3 -m json.tool 2>/dev/null || cat "$DATA_DIR/out/state.json"
echo ""
fi
fi
# Offer to open output directory
echo "📂 Output location: $DATA_DIR/out/"
echo ""
echo "View output:"
echo " ls -lh $DATA_DIR/out/tables/"
echo " head $DATA_DIR/out/tables/*.csv"
else
echo "❌ Component failed (exit code: $EXIT_CODE, duration: $DURATION seconds)"
echo ""
echo "Common issues:"
echo " • Exit code 1: User error (invalid config, missing params)"
echo " • Exit code 2: System error (network, API, unexpected exception)"
echo ""
echo "Debug steps:"
echo " 1. Check error message above"
echo " 2. Verify config: cat $CONFIG_FILE"
echo " 3. Check logs for details"
echo " 4. Run with debugger: python -m pdb src/component.py"
echo ""
fi
Ask if user wants to clean output for next run:
# Only ask if run was successful
if [ $EXIT_CODE -eq 0 ]; then
echo "💡 Tip: To run again with fresh output, clean the out/ directory:"
echo " rm -rf $DATA_DIR/out/*"
fi
Create multiple config files for different scenarios:
# Create configs
cat > data/config-minimal.json << 'EOF'
{"parameters": {"debug": true}}
EOF
cat > data/config-full.json << 'EOF'
{"parameters": {"api_url": "...", "limit": 100}}
EOF
# Run with different configs
/run data/config-minimal.json
/run data/config-full.json
# Create input table
cat > data/in/tables/users.csv << 'EOF'
id,name,email
1,John Doe,john@example.com
2,Jane Smith,jane@example.com
EOF
# Create manifest
cat > data/in/tables/users.csv.manifest << 'EOF'
{
"id": "users",
"primary_key": ["id"]
}
EOF
# Run component
/run
# Run with Python debugger
python -m pdb src/component.py
# Or with verbose logging
export KBC_LOGGER_VERBOSITY=verbose
/run --verbose
# Check component logs
tail -f logs/component.log # if logging to file
# Fix permissions
chmod -R u+w data/
# Install dependencies
uv sync
# or
pip install -e .
# Check Python version
python --version
# Use correct version
python3.11 src/component.py
This command handles it automatically - sets KBC_DATADIR=data before running.
User: /run
Assistant: Running component locally...
✓ Data directory structure ready: data
📦 Checking dependencies (uv)...
🚀 Running component...
Config: data/config.json
Data dir: data
Command: uv run python src/component.py
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
INFO:root:Extracting data from API...
INFO:root:Processing 150 records...
INFO:root:Writing output table: users.csv
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Component completed successfully (3 seconds)
📊 Output tables:
• users.csv (151 lines, 24K)
📂 Output location: data/out/
View output:
ls -lh data/out/tables/
head data/out/tables/*.csv
💡 Tip: To run again with fresh output, clean the out/ directory:
rm -rf data/out/*
For related commands:
/test - Run pytest tests/debug - Debug failed Keboola jobs@build-component - Implementation help