Initialize‑Shp

SYNOPSIS

Performs the GitHub OAuth device-code flow and caches the access token.

SYNTAX

Initialize-Shp [[-TokenPath] <String>] [[-GitHubHost] <String>] [[-ClientId] <String>] [[-Scope] <String>]
 [-Force] [-NonInteractive] [<CommonParameters>]

DESCRIPTION

Uses the public VS Code GitHub Copilot Chat client_id to run the GitHub device-code authorization flow. The function prints a verification URL and user code, opens the browser, copies the code to the clipboard, polls GitHub until the user authorizes (or the code expires), and writes the resulting OAuth token to -TokenPath for later reuse by Get-ShpModel and Invoke-Shp.

The device-code flow needs a person and a browser, so it is the wrong entry point for a pipeline. An unattended caller supplies the OAuth token in memory instead - $env:SHELLPILOT_GITHUB_TOKEN or Set-ShpContext -GitHubToken - and never calls this function at all. -NonInteractive says so up front rather than letting a runner block on a browser that will never open.

EXAMPLES

EXAMPLE 1

Initialize-Shp

Authenticates interactively (if no cached token exists) and writes the token to the default path.

EXAMPLE 2

Initialize-Shp -Force

Forces a fresh device-code login even when a cached token is present.

PARAMETERS

-ClientId

OAuth client_id. Default: the public VS Code Copilot Chat client.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 3
Default value: $script:DefaultClientId
Accept pipeline input: False
Accept wildcard characters: False

-Force

Re-authenticate even if a token file already exists at -TokenPath.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-GitHubHost

HTTPS GitHub.com or Enterprise Cloud GHE.com sign-in origin. Overrides Session context and SHELLPILOT_GITHUB_HOST; defaults to https://github.com. Use the same host for later API calls. No credential format or entitlement is inferred from this setting; use a token belonging to the selected host.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-NonInteractive

Run unattended: never open a browser, never write to the clipboard, and fail with a terminating error rather than start a device-code flow that has nobody to complete it. An existing token file is still returned. It is on automatically when $env:CI is truthy; pass -NonInteractive:$false to override that detection.

In CI this function is also refused outright unless SHELLPILOT_ALLOW_COPILOT_BACKEND_IN_CI is set, because signing in here exists only to enable Copilot-backend calls on a person's entitlement. See Test-ShpCiReadiness.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-Scope

OAuth scope requested during the device flow. Default: read:user.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 4
Default value: Read:user
Accept pipeline input: False
Accept wildcard characters: False

-TokenPath

File path for the cached token. Default: .shellpilot-token in your home directory (%USERPROFILE% on Windows, $HOME on Linux/macOS).

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 1
Default value: $script:DefaultTokenPath
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

OUTPUTS

System.IO.FileInfo

The file that contains the cached OAuth token.

NOTES

The token is written through the at-rest seam: DPAPI-encrypted for the current Windows account, or mode 600 with the scheme recorded in the file on Linux and macOS. See specs/020-encrypted-token-storage.md for what that does and does not protect against.

RELATED LINKS

Get-ShpModel

Invoke-Shp

Test-ShpCiReadiness