Set‑ShpContext

SYNOPSIS

Sets session-wide connection options for the ShellPilot cmdlets.

SYNTAX

Set-ShpContext [[-TimeoutSec] <Int32>] [[-MaxRetryCount] <Int32>] [[-RetryDelaySec] <Int32>]
 [[-NetworkOutageToleranceSec] <Int32>] [[-MaxContextWindowTokens] <Int32>] [[-ApiBase] <String>]
 [[-ApiKey] <String>] [[-GitHubToken] <String>] [[-GitHubHost] <String>] [-PassThru]
 [-WhatIf] [-Confirm] [<CommonParameters>]

DESCRIPTION

Stores connection-level options in a module-scoped session context that Invoke-Shp and the other API cmdlets apply when the matching parameter is not supplied on the call. The resolution precedence is always: an explicit parameter wins, then this session context, then the built-in default. Only the parameters you pass are changed; the rest keep their current value. The context is held in memory for the current PowerShell session and is never written to disk. Read it with Get-ShpContext and reset it with Clear-ShpContext.

Every HTTP request the module makes honours these options, including the OAuth-to-session token exchange, /models and embeddings. There is no exemption for the auth handshake: a setting that applies to the chat turn but not to the request that precedes it is one the caller cannot see failing. The exchange is cached for the life of a session token, so MaxRetryCount 0 costs at most one un-retried attempt per session, and outage tolerance is a separate option - so disabling 429/5xx retry still leaves a dropped connection during auth to be ridden out.

The ApiBase and ApiKey options enable an opt-in alternative, OpenAI-compatible backend (for example a self-hosted server). They are off unless you set them and are never a default; clear them to return to the standard Copilot session-token authentication.

The GitHubToken option supplies the GitHub OAuth token in memory, for a pipeline or any other caller that cannot run the interactive device-code flow. It is held for the session only and is never written to disk - Initialize-Shp remains the only code path that writes a token file.

EXAMPLES

EXAMPLE 1

Set-ShpContext -TimeoutSec 30 -MaxRetryCount 5

Makes subsequent ShellPilot API calls time out after 30 seconds and retry up to five times on a transient failure.

EXAMPLE 2

Set-ShpContext -ApiBase 'http://localhost:11434/v1' -ApiKey 'sk-local'

Points ShellPilot at a local OpenAI-compatible server (opt-in).

EXAMPLE 3

Set-ShpContext -GitHubToken $tokenFromVault

Authenticates this session from a token held in memory, with no token file on disk and no interactive sign-in.

PARAMETERS

-ApiBase

Opt-in base URL of an alternative, OpenAI-compatible endpoint to use instead of the Copilot session endpoint. Off unless set; never a default. Pair with -ApiKey for bearer authentication.

Type: String
Parameter Sets: (All)
Aliases:

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

-ApiKey

Opt-in API key (bearer token) sent when -ApiBase points at an alternative backend. Ignored when no ApiBase is set.

Type: String
Parameter Sets: (All)
Aliases:

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

-GitHubHost

HTTPS GitHub.com or Enterprise Cloud GHE.com authentication origin for subsequent API calls. Overrides SHELLPILOT_GITHUB_HOST, but not an explicit per-call host. Invalid or empty origins are refused before changing context. Changing hosts clears host-dependent model caches.

Type: String
Parameter Sets: (All)
Aliases:

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

-GitHubToken

GitHub OAuth token to authenticate with for this session, instead of the token file Initialize-Shp writes. Held in memory only and never persisted. It is used when a call does not name its own -TokenPath, and it wins over $env:SHELLPILOT_GITHUB_TOKEN and the default token file. Masked as *** by Get-ShpContext and by -PassThru.

Type: String
Parameter Sets: (All)
Aliases:

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

-MaxContextWindowTokens

Estimated-token budget for the accumulated conversation of a single turn, above which Invoke-Shp elides the oldest tool results before the next request. This is step 2 of four: an explicit Invoke-Shp -MaxContextWindowTokens wins over it, and it wins over both the model's own advertised limits (step 3, available once Get-ShpModel has run this session) and the built-in 900000 (step 4). Setting it here therefore pins the budget for every model, which is what you want for a fixed-model workload and not what you want for a mixed one - leave it unset and call Get-ShpModel once to let each turn size itself. 0 disables the guard.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: 5
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False

-MaxRetryCount

Number of additional attempts made when a request fails with a transient error (HTTP 429 or 5xx) before giving up. Built-in default: 3.

Type: Int32
Parameter Sets: (All)
Aliases:

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

-NetworkOutageToleranceSec

Wall-clock budget, in seconds, for riding out a connection-level network outage - a dropped connection that returns no HTTP response. Every API call is retried until this many seconds have elapsed since the first connection failure, then the error is rethrown. Built-in default: 30. 0 disables outage tolerance.

Type: Int32
Parameter Sets: (All)
Aliases:

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

-PassThru

Return the updated context object after setting it.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-RetryDelaySec

Base delay in seconds for the exponential backoff between retries. Built-in default: 2.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: 3
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False

-TimeoutSec

Per-request HTTP timeout in seconds applied to API calls when a call does not specify its own. Built-in default: 0, meaning no explicit timeout - the shared HttpClient is built with an infinite timeout so a long streamed turn is not cut off mid-response.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: 1
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf

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

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi

Required: False
Position: Named
Default value: None
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

None by default; the session context object when -PassThru is used.

NOTES

RELATED LINKS

Get-ShpContext

Clear-ShpContext