Skip to content

Get-FilesUsingKeywords.md

Latest commit

 

History

History
132 lines (109 loc) · 3.9 KB

Get-FilesUsingKeywords.md

File metadata and controls

132 lines (109 loc) · 3.9 KB
Raw

Get-FilesUsingKeywords

Synopsis

Searches files in a directory for one or more keywords.

Description

Recursively searches files under a given directory for lines matching any of the supplied keywords. The search always runs asynchronously: a PowerShell runspace is used for local execution and Invoke-Command -AsJob is used for remote execution. Either way Wait-TerminalState drives the poll/spinner loop until completion.

Syntax

Get-FilesUsingKeywords [-Path] <string> [-Keywords] <string[]> [[-ComputerName] <string>] [[-Credential] <pscredential>] [[-FileFilter] <string>] [-NoRecurse] [-CaseSensitive] [-SimpleMatch] [-UseSsh] [-UseCredSSP] [-SshPort <int>] [-TimeoutSeconds <int>] [-PollSeconds <int>]

Parameters

-Path

The directory to search. Required.

  • Type: string
  • Required: true
  • Position: 1
  • Default value: None

-Keywords

One or more keywords (or regex patterns) to search for within file contents. Required.

  • Type: string[]
  • Required: true
  • Position: 2
  • Default value: None

-ComputerName

Remote computer to run the search on. When omitted the search runs locally.

  • Type: string
  • Required: false
  • Position: named
  • Default value: Localhost

-Credential

Credentials used when connecting to the remote machine or accessing a protected directory path.

  • Type: pscredential
  • Required: false
  • Position: named
  • Default value: None

-FileFilter

Wildcard filter applied to file names (e.g. '.log', '.txt'). Defaults to '*' (all files).

  • Type: string
  • Required: false
  • Position: named
  • Default value: '*'

-NoRecurse

When specified, only the top-level directory is searched instead of recursing into subdirectories.

  • Type: switch
  • Required: false
  • Position: named
  • Default value: False (recursion enabled)

-CaseSensitive

Treat keyword matching as case-sensitive.

  • Type: switch
  • Required: false
  • Position: named
  • Default value: False (case-insensitive)

-SimpleMatch

Treat keywords as literal strings rather than regular expressions.

  • Type: switch
  • Required: false
  • Position: named
  • Default value: False (regex matching)

-UseSsh

Enable SSH-based remote execution.

  • Type: switch
  • Required: false
  • Position: named
  • Default value: False

-UseCredSSP

Enable CredSSP authentication for remote execution.

  • Type: switch
  • Required: false
  • Position: named
  • Default value: False

-SshPort

The SSH port to use when using SSH. Defaults to 22.

  • Type: int
  • Required: false
  • Position: named
  • Default value: 22

-TimeoutSeconds

Maximum time in seconds to wait for the search job to complete. Valid range: 10 to 86400.

  • Type: int
  • Required: false
  • Position: named
  • Default value: 1200

-PollSeconds

Interval in seconds between polling checks for job completion. Valid range: 1 to 3600.

  • Type: int
  • Required: false
  • Position: named
  • Default value: 30

Inputs

None. You cannot pipe objects to Get-FilesUsingKeywords.

Outputs

The function returns file paths and matching content lines where keywords are found.

Examples

Example 1: Search local directory for a keyword

Get-FilesUsingKeywords -Path 'C:\Logs' -Keywords 'error'

This command searches all files in the C:\Logs directory for the word "error".

Example 2: Search with file filter and no recursion

Get-FilesUsingKeywords -Path 'C:\Data' -Keywords 'critical' -FileFilter '*.txt' -NoRecurse

This command searches only .txt files in the top-level C:\Data directory for "critical".

Example 3: Remote search with credentials

$cred = Get-Credential
Get-FilesUsingKeywords -Path 'C:\AppLogs' -Keywords 'exception' -ComputerName 'Server01' -Credential $cred

This command searches files on a remote computer using provided credentials.