Skip to main content

​
Overview

This quickstart will take you from zero to analyzing your first project portfolio in under 5 minutes. You’ll install Artifact Miner, start the API server, upload a test ZIP, and view the extracted insights.
Prerequisites: Python 3.11+, uv package manager, and Git. See the Installation guide for detailed setup.

​
Installation

1

Clone the repository

git clone <repository-url>
cd artifactminer
2

Install dependencies

uv sync
This installs all required packages including FastAPI, SQLAlchemy, GitPython, and the Textual TUI framework.
3

Set up environment

cp .env.example .env
The default .env configuration works for local development:
# Base URL for the FastAPI server
API_BASE_URL=http://127.0.0.1:8000

# OpenTUI React API client configuration
ARTIFACT_MINER_API_URL=http://127.0.0.1:8000
ARTIFACT_MINER_TIMEOUT=30000
4

Initialize the database

uv run alembic upgrade head
This creates artifactminer.db and applies all schema migrations.

​
Start the API Server

Launch the FastAPI backend: 
uv run api
You should see output like: 
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using WatchFiles
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
Visit http://127.0.0.1:8000/docs to explore the interactive API documentation powered by FastAPI’s built-in Swagger UI.

​
Verify Installation

Check that the API is healthy: 
curl http://127.0.0.1:8000/health
Expected response: 
{"status": "healthy"}

​
Upload Your First Project

Launch the interactive terminal interface: 
uv run artifactminer-tui
The TUI guides you through a visual workflow:
1

Consent Screen

Choose your consent level:
  • local: No external services
  • local-llm: Use local Ollama for summaries
  • cloud: Use OpenAI API (requires API key)
  • none: Minimal processing
2

User Configuration

Answer setup questions:
  • Email address
  • Analysis goals
  • File filters (optional)
3

Upload ZIP

Browse to a ZIP file containing one or more Git repositories. The system will:
  • Extract the archive to .extracted/
  • Scan for Git repositories
  • Display discovered projects
4

Select Repositories

Choose which repositories to analyze from the discovered list.
5

View Results

The TUI displays:
  • Project timeline (commit activity windows)
  • Skills chronology (when each skill was first used)
  • Resume items (auto-generated bullets)

​
Option 2: Using the CLI

For non-interactive workflows, use the CLI: 
# Guided prompts
uv run artifactminer

​
CLI Options

FlagDescriptionDefault
-i, --inputPath to ZIP file(required in non-interactive mode)
-o, --outputOutput file path (.txt or .json)(required in non-interactive mode)
-c, --consentConsent level: full, no_llm, noneno_llm
-u, --user-emailUser email for tracking[email protected]
CLI consent flags use full | no_llm | none, while the API /consent endpoint uses local | local-llm | cloud | none.

​
Option 3: Using the API Directly

For programmatic access or custom integrations:
1

Set consent preferences

curl -X PUT http://127.0.0.1:8000/consent \
  -H "Content-Type: application/json" \
  -d '{"consent_level": "local", "LLM_model": "none"}'
2

Upload a ZIP file

curl -X POST http://127.0.0.1:8000/zip/upload \
  -F "file=@/path/to/projects.zip" \
  -F "portfolio_id=test-portfolio-1"
Response:
{
  "zip_id": 1,
  "filename": "projects.zip",
  "portfolio_id": "test-portfolio-1",
  "uploaded_at": "2026-03-05T10:30:00"
}
3

Trigger analysis

curl -X POST http://127.0.0.1:8000/analyze/1
This extracts repositories, runs git analysis, and computes skills/evidence.
4

Retrieve results

curl http://127.0.0.1:8000/projects

​
Understanding the Output

​
Project Timeline

Shows when each project was active: 
● project-alpha
    2023-01-15 → 2024-06-20 (521 days)
○ project-beta
    2022-03-01 → 2022-08-15 (167 days)
  • ● = Recently active (within 6 months)
  • ○ = Inactive

​
Skills Chronology

Tracks when you first demonstrated each skill: 
{
  "Languages": [
    {
      "skill": "Python",
      "first_used": "2022-03-01",
      "project": "project-beta"
    },
    {
      "skill": "JavaScript",
      "first_used": "2023-01-15",
      "project": "project-alpha"
    }
  ],
  "Frameworks": [
    {
      "skill": "React",
      "first_used": "2023-02-20",
      "project": "project-alpha"
    }
  ]
}

​
Resume Items

Auto-generated resume bullets based on repository intelligence: 
[
  {
    "project_name": "project-alpha",
    "description": "Built full-stack web application using React and FastAPI",
    "evidence": ["src/api/app.py", "frontend/src/App.tsx"],
    "skills": ["React", "FastAPI", "Python", "TypeScript"]
  }
]

​
Next Steps

Installation Guide

Detailed setup instructions, environment configuration, and troubleshooting

API Reference

Complete API endpoint documentation with request/response examples

CLI Usage

Advanced CLI workflows, batch processing, and automation

TUI Guide

Explore all features of the Textual terminal interface
Always run uv run alembic upgrade head after pulling updates to ensure your database schema is current.

Build docs developers (and LLMs) love

Get started for freeTalk to us