chore: promote develop to main

PiHoleShell/PiHoleShell.psm1

@@ -34,7 +34,9 @@ Export-ModuleMember -Function @(
         'Get-PiHoleList', 'Search-PiHoleListDomain', 'Add-PiHoleList', 'Remove-PiHoleList', 'Update-PiHoleList', `
         #FTLInformation
         'Get-PiHoleInfoMessage', 'Get-PiHoleInfoHost', 'Get-PiHoleInfoClient', 'Get-PiHoleInfoLogin', 'Get-PiHoleInfoSystem', 'Get-PiHoleInfoFtl', `
-        'Get-PiHoleInfoSensors', 'Get-PiHoleInfoDatabase', 'Get-PiHoleInfoVersion', 'Get-PiHoleInfoMetrics', 'Get-PiHoleInfoMessageCount', 'Remove-PiHoleInfoMessage', `
+        'Get-PiHoleInfoSensors', 'Get-PiHoleInfoDatabase', 'Get-PiHoleInfoVersion', 'Get-PiHoleInfoMetrics', 'Get-PiHoleInfoMessageCount', 'Remove-PiHoleInfoMessage', 'Get-PiHoleLogWebserver', `
         #History
-        'Get-PiHoleHistory', 'Get-PiHoleHistoryDatabase', 'Get-PiHoleHistoryClient', 'Get-PiHoleHistoryDatabaseClient'
+        'Get-PiHoleHistory', 'Get-PiHoleHistoryDatabase', 'Get-PiHoleHistoryClient', 'Get-PiHoleHistoryDatabaseClient', `
+        #Teleporter
+        'Get-PiHoleTeleporterDownload'
 )

PiHoleShell/Public/FTLInformation/Get-PiHoleLogWebserver.ps1

@@ -1,31 +1,49 @@
-
 function Get-PiHoleLogWebserver {
     <#
 .SYNOPSIS
-Get info about logs for webserver
+Get webserver log content
+
+.DESCRIPTION
+Request content from the log of the embedded CivetWeb HTTP server. Every response includes a
+NextID; pass it back as -NextID on your next call to only get lines added since then, making
+periodic polling for new log lines easy without checking for duplicates.
+
+.PARAMETER PiHoleServer
+The URL to the PiHole Server, for example "http://pihole.domain.com:8080", or "http://192.168.1.100"
+
+.PARAMETER Password
+The API Password you generated from your PiHole server
+
+.PARAMETER NextID
+Only return log lines added after this ID (returned as NextID on a previous call). Omit to
+get the full available log
+
+.PARAMETER IgnoreSsl
+Set to $true to skip SSL certificate validation
 
+.PARAMETER RawOutput
+This will dump the response instead of the formatted object
+
+.EXAMPLE
+Get-PiHoleLogWebserver -PiHoleServer "http://pihole.domain.com:8080" -Password "your-app-password"
     #>
-    #Work In Progress
     [CmdletBinding(HelpUri = 'https://ftl.pi-hole.net/master/docs/#get-/logs/webserver')]
     [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPlainTextForPassword", "Password")]
     param (
         [Parameter(Mandatory = $true)]
         [System.URI]$PiHoleServer,
         [Parameter(Mandatory = $true)]
         [string]$Password,
-        [int]$NextID,
+        [Nullable[int]]$NextID,
         [bool]$IgnoreSsl = $false,
         [bool]$RawOutput = $false
     )
     try {
         $Sid = Request-PiHoleAuth -PiHoleServer $PiHoleServer -Password $Password -IgnoreSsl $IgnoreSsl
 
-        if ($NextID) {
-            $Uri = "$($PiHoleServer.OriginalString)/api/logs/webserver?nextId=$NextId"
-
-        }
-        else {
-            $Uri = "$($PiHoleServer.OriginalString)/api/logs/webserver"
+        $Uri = "$($PiHoleServer.OriginalString)/api/logs/webserver"
+        if ($PSBoundParameters.ContainsKey('NextID')) {
+            $Uri += "?nextID=$NextID"
         }
 
         $Params = @{
@@ -43,18 +61,31 @@ Get info about logs for webserver
         }
 
         else {
-            #$ObjectFinal = @()
+            $Log = foreach ($Item in $Response.log) {
+                [PSCustomObject]@{
+                    Timestamp = (Convert-PiHoleUnixTimeToLocalTime -UnixTime $Item.timestamp).LocalTime
+                    Message   = $Item.message
+                    Priority  = $Item.prio
+                }
+            }
+
+            $Object = [PSCustomObject]@{
+                Log    = $Log
+                NextID = $Response.nextID
+                Pid    = $Response.pid
+                File   = $Response.file
+            }
+            Write-Output $Object
         }
     }
 
     catch {
         Write-Error -Message $_.Exception.Message
-        break
     }
 
     finally {
         if ($Sid) {
             Remove-PiHoleCurrentAuthSession -PiHoleServer $PiHoleServer -Sid $Sid -IgnoreSsl $IgnoreSsl
         }
     }
-}
+}

PiHoleShell/Public/ListManagement/Get-PiHoleList.ps1

@@ -3,20 +3,31 @@ function Get-PiHoleList {
 .SYNOPSIS
 Get lists
 
+.DESCRIPTION
+Request Pi-hole's subscribed allow/block lists. Omit -List to get every list; specify it to
+get just that one.
+
 .PARAMETER PiHoleServer
 The URL to the PiHole Server, for example "http://pihole.domain.com:8080", or "http://192.168.1.100"
 
 .PARAMETER Password
 The API Password you generated from your PiHole server
 
+.PARAMETER List
+The URL of a specific list to return. Omit to return every list
+
 .PARAMETER IgnoreSsl
 Set to $true to skip SSL certificate validation
 
 .PARAMETER RawOutput
 This will dump the response instead of the formatted object
 
+.EXAMPLE
+Get-PiHoleList -PiHoleServer "http://pihole.domain.com:8080" -Password "your-app-password"
+
+.EXAMPLE
+Get-PiHoleList -PiHoleServer "http://pihole.domain.com:8080" -Password "your-app-password" -List "https://hosts-file.net/ad_servers.txt"
     #>
-    #Work In Progress
     [CmdletBinding(HelpUri = 'https://ftl.pi-hole.net/master/docs/#get-/lists/-list-')]
     [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPlainTextForPassword", "Password")]
     param (

PiHoleShell/Public/Teleporter/Get-PiHoleTeleporterDownload.ps1

@@ -1,11 +1,32 @@
 function Get-PiHoleTeleporterDownload {
     <#
 .SYNOPSIS
-Get info about logs for webserver
+Export Pi-hole settings
 
+.DESCRIPTION
+Downloads an archived copy of Pi-hole's current configuration (a Teleporter backup) to disk.
+The API always returns a binary application/zip archive, not JSON, so there's no -RawOutput
+option here - the downloaded file is the only output.
+
+.PARAMETER PiHoleServer
+The URL to the PiHole Server, for example "http://pihole.domain.com:8080", or "http://192.168.1.100"
+
+.PARAMETER Password
+The API Password you generated from your PiHole server
+
+.PARAMETER FolderPath
+The folder to save the backup file into. Must already exist
+
+.PARAMETER FileName
+The name to give the backup file, without an extension - ".zip" is appended automatically
+
+.PARAMETER IgnoreSsl
+Set to $true to skip SSL certificate validation
+
+.EXAMPLE
+Get-PiHoleTeleporterDownload -PiHoleServer "http://pihole.domain.com:8080" -Password "your-app-password" -FolderPath "C:\Backups" -FileName "pihole-backup"
     #>
-    #Work In Progress
-    [CmdletBinding()]
+    [CmdletBinding(HelpUri = 'https://ftl.pi-hole.net/master/docs/#get-/teleporter')]
     [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPlainTextForPassword", "Password")]
     param (
         [Parameter(Mandatory = $true)]
@@ -16,56 +37,46 @@ Get info about logs for webserver
         [System.IO.DirectoryInfo]$FolderPath,
         [Parameter(Mandatory = $true)]
         [string]$FileName,
-        [bool]$IgnoreSsl = $false,
-        [bool]$RawOutput = $false
+        [bool]$IgnoreSsl = $false
     )
     try {
-        $Sid = Request-PiHoleAuth -PiHoleServer $PiHoleServer -Password $Password -IgnoreSsl $IgnoreSsl
-
         if (!(Test-Path -Path $FolderPath)) {
             throw "$FolderPath does not exist!"
         }
-        $FileName = "$FileName.tar.gz"
+        $FileName = "$FileName.zip"
         $OutFile = "$FolderPath\$FileName"
         if (Test-Path -Path $OutFile) {
             throw "$OutFile already exists!"
         }
 
+        $Sid = Request-PiHoleAuth -PiHoleServer $PiHoleServer -Password $Password -IgnoreSsl $IgnoreSsl
+
         $Params = @{
             Headers              = @{sid = $($Sid) }
             Uri                  = "$($PiHoleServer.OriginalString)/api/teleporter"
             Method               = "Get"
             SkipCertificateCheck = $IgnoreSsl
-            ContentType          = "application/json"
+            OutFile              = $OutFile
         }
 
-        $Response = Invoke-RestMethod @Params -OutFile $OutFile
-
-        if ($RawOutput) {
-            Write-Output $Response
-        }
+        Invoke-RestMethod @Params
 
-        else {
-            $ObjectFinal = @()
-            $Object = [PSCustomObject]@{
-                FileName   = $FileName
-                FilePath   = $OutFile
-                RootFolder = $FolderPath
-                FileSizeKB = [math]::Ceiling((Get-Item $OutFile).Length / 1KB)
-            }
-            $ObjectFinal += $Object
-            Write-Output $ObjectFinal
+        $Object = [PSCustomObject]@{
+            FileName   = $FileName
+            FilePath   = $OutFile
+            RootFolder = $FolderPath
+            FileSizeKB = [math]::Ceiling((Get-Item $OutFile).Length / 1KB)
         }
+        Write-Output $Object
     }
 
     catch {
         Write-Error -Message $_.Exception.Message
-        break
     }
 
     finally {
         if ($Sid) {
             Remove-PiHoleCurrentAuthSession -PiHoleServer $PiHoleServer -Sid $Sid -IgnoreSsl $IgnoreSsl
         }
     }
-}
+}

README.md

@@ -18,6 +18,7 @@ A PowerShell module for automating and scripting against the **Pi-hole v6 REST A
 - [Getting an API Password](#getting-an-api-password)
 - [Quick Start](#quick-start)
 - [Command Reference](#command-reference)
+- [Example Output](docs/EXAMPLES.md)
 - [Testing](#testing)
 - [Contributing](#contributing)
 - [License](#license)
@@ -82,6 +83,8 @@ Every function accepts the same core parameters:
 
 Functions marked 🚧 are still under active development — signatures and output shapes may change. This section is generated from the module's actual exported functions by `tools/Update-ReadmeCommandReference.ps1`, and kept in sync automatically on every `develop` → `main` pull request — don't hand-edit the block below.
 
+See [docs/EXAMPLES.md](docs/EXAMPLES.md) for real, captured output from every function below.
+
 <!-- COMMAND-REFERENCE:START -->
 ### Actions
 
@@ -113,7 +116,7 @@ Functions marked 🚧 are still under active development — signatures and outp
 | Function | Description |
 |---|---|
 | `Add-PiHoleList` | Add a new list |
-| `Get-PiHoleList` 🚧 | Get lists |
+| `Get-PiHoleList` | Get lists |
 | `Remove-PiHoleList` | Remove a list |
 | `Search-PiHoleListDomain` | _No description yet_ |
 | `Update-PiHoleList` | Update a list |
@@ -155,7 +158,9 @@ Functions marked 🚧 are still under active development — signatures and outp
 | `Get-PiHoleInfoSensors` | Get info about various sensors |
 | `Get-PiHoleInfoSystem` | Get info about various system parameters |
 | `Get-PiHoleInfoVersion` | Get Pi-hole version |
+| `Get-PiHoleLogWebserver` | Get webserver log content |
 | `Get-PiHolePadd` | Get summarized data for PADD |
+| `Get-PiHoleTeleporterDownload` | Export Pi-hole settings |
 | `Remove-PiHoleInfoMessage` | Delete a Pi-hole diagnosis message |
 
 ### Authentication