Skip to content

Your First 5 Minutes

🚀 Your First 5 Minutes with Sierra DevLink

Build your first investigation tool from scratch in 5 minutes!

What You'll Learn

  • Create a working invoker
  • Compile it to a standalone tool
  • Run it and see formatted results
  • Understand the complete workflow

🎯 The GoalLink

We're building url_analyzer - a simple tool that:

  1. Takes a URL as input
  2. Extracts basic information
  3. Displays results in a table

Step 1: Create Environment (30 seconds)Link

Make sure Sierra Dev is installed first!

If you haven't installed it yet, see the Installation Guide.

Open your terminal and run:

Bash
1
2
sierra-dev init my_first_project
cd my_first_project

✅ You now have:

Text Only
1
2
3
4
my_first_project/
├── scripts/       # Your code goes here
├── config.yaml    
└── source

Step 2: Write Your First Invoker (2 minutes)Link

Create a new file scripts/url_analyzer.py:

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
"""
URL Analyzer - Extract information from URLs.
"""
from urllib.parse import urlparse
import sierra

# 1. Define the invoker
invoker = sierra.InvokerScript(
    name="url_analyzer",
    description="Analyze and extract information from a URL"
)

# 2. Helper function (optional)
@invoker.dependancy
def analyze_url(url: str) -> dict[str, str]:
    """Parse URL and extract components."""
    parsed = urlparse(url)
    return {
        "scheme": parsed.scheme or "none",
        "domain": parsed.netloc or "none",
        "path": parsed.path or "/",
        "params": parsed.params or "none"
    }

# 3. Main entry point
@invoker.entry_point
def run(
    url: sierra.Param[
        str | None,
        sierra.SierraOption(
            description="URL to analyze",
            mandatory="MANDATORY"
        )
    ]
) -> None:
    """Analyze a URL and display components."""

    # Validate input
    if url is None:
        result = sierra.create_error_result("URL is required!")
        sierra.respond(result)
        return

    # Analyze the URL
    info = analyze_url(url)

    # Create a table result
    rows = [
        ["Scheme", info["scheme"]],
        ["Domain", info["domain"]],
        ["Path", info["path"]],
        ["Parameters", info["params"]]
    ]

    result = sierra.Table(
        headers=["Component", "Value"],
        rows=rows
    )

    # Send the result
    sierra.respond(result)

# 4. Register with Sierra
def load(client: sierra.SierraDevelopmentClient) -> None:
    client.load_invoker(invoker)

Let's break down each part:

1. Import and Define

Python
1
2
3
4
5
6
import sierra

invoker = sierra.InvokerScript(
    name="url_analyzer",
    description="Analyze and extract information from a URL"
)
- Import Sierra Dev - Create an invoker with name and description

2. Helper Function (Optional)

Python
1
2
3
4
@invoker.dependancy
def analyze_url(url: str) -> dict[str, str]:
    # Your logic here
    return data
- Marked with @invoker.dependancy - Can be reused by other functions - Gets included in compilation

3. Entry Point (Required)

Python
1
2
3
4
5
6
@invoker.entry_point
def run(
    url: sierra.Param[str | None, sierra.SierraOption(...)]
) -> None:
    # Main logic
    sierra.respond(result)
- Must be named run - Marked with @invoker.entry_point - Parameters use sierra.Param for validation - Must call sierra.respond(result) at the end

4. Loader (Required)

Python
1
2
def load(client):
    client.load_invoker(invoker)
- Registers your invoker with Sierra - Required for discovery

Step 3: Build (Compile) Your Invoker (30 seconds)Link

This converts your source code into a standalone tool:

Bash
1
sierra-dev build --env my_first_project

What happens:

graph LR
    A[scripts/url_analyzer.py] -->|Read| B[Validate]
    B -->|Transform| C[Generate CLI]
    C -->|Write| D[invokers/url_analyzer.py]

    style A fill:#bc13fe20
    style D fill:#00f3ff20

✅ Look for this output:

Text Only
1
2
3
4
5
Building Sierra project...
Sierra: Compile: Starting process
Sierra: Dependencies installed successfully
Sierra: Compile: Completed process
Build completed successfully.

Step 4: Test Your Tool (1 minute)Link

Now let's run it!

Get HelpLink

Bash
1
my_first_project/venv/bin/python my_first_project/invokers/url_analyzer.py --help

Output:

Text Only
1
2
3
4
5
6
usage: url_analyzer.py [--url URL]

Analyze and extract information from a URL

optional arguments:
  --url URL    URL to analyze

Run It!Link

Bash
1
2
my_first_project/venv/bin/python my_first_project/invokers/url_analyzer.py \
    --url "https://github.com/xsyncio/sierra-dev"

Output (JSON):

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "type": "Table",
  "headers": ["Component", "Value"],
  "rows": [
    ["Scheme", "https"],
    ["Domain", "github.com"],
    ["Path", "/xsyncio/sierra-dev"],
    ["Parameters", "none"]
  ]
}

🎉 Congratulations! You just created your first Sierra invoker!

🎓 What You LearnedLink

Concept What It Is Example
Invoker A structured tool url_analyzer
Helper Function Reusable logic analyze_url()
Entry Point Main execution run() function
Parameter Input with validation url parameter
Result Formatted output sierra.Table
Compilation Source → Standalone scripts/ → invokers/

🚀 Next StepsLink

Level Up Your SkillsLink

Try enhancing url_analyzer:

Python
1
2
3
4
5
# Add a parameter
verbose: sierra.Param[
    bool | None,
    sierra.SierraOption(description="Show detailed output")
] = False

Rebuild and test:

Bash
1
sierra-dev build --env my_first_project

Instead of sierra.Table, try:

Tree Result:

Python
1
2
3
4
result = sierra.create_tree_result([
    "URL Analysis",
    {"Components": ["scheme", "domain", "path"]}
])

Error Result:

Python
1
result = sierra.create_error_result("Invalid URL format")

Explore community tools:

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Add package repository
sierra-dev repo add https://github.com/xsyncio/sierra-invokers

# Search for tools
sierra-dev search domain

# Install a tool
sierra-dev install whois_lookup

# Build
sierra-dev build --env my_first_project

Deep Dive DocumentationLink

Topic Where to Go
Understand the concepts Core Concepts
Master CLI commands CLI Reference
Learn result types Results Guide
Use packages Package Manager
Advanced techniques Development Guide

💡 TroubleshootingLink

Build failed with validation errors

Common causes:

  • ❌ Invoker name has hyphens → Use underscores
  • ❌ Missing type annotations → Add : str, etc.
  • ❌ No entry point → Add @invoker.entry_point

Run with --verbose for details:

Bash
1
sierra-dev build --env my_first_project --verbose

ImportError: No module named 'sierra'

Solution: Make sure virtual environment is activated

Bash
1
2
source my_first_project/venv/bin/activate  # Linux/macOS
my_first_project\venv\Scripts\activate    # Windows
How do I modify the invoker?
  1. Edit scripts/url_analyzer.py
  2. Run sierra-dev build --env my_first_project again
  3. Test the invokers/url_analyzer.py version

🎯 Challenge Yourself!Link

Ready to practice? Try building these:

🔰 BeginnerLink

  • Email Validator - Check if an email format is valid
  • File Size Analyzer - Show file sizes in a directory

⭐ IntermediateLink

  • IP Lookup - Get geolocation from IP address
  • Hash Generator - Generate MD5/SHA256 hashes

💎 AdvancedLink

  • Port Scanner - Scan common ports on a target
  • DNS Resolver - Query DNS records

🚀 You're now a Sierra Dev developer!

Learn Core Concepts → Explore Result Types