format, lint and document new flags

Author: friggeri

.github/aw/github-agentic-workflows.md

@@ -214,18 +214,18 @@ The YAML frontmatter supports these fields:
     The `custom` engine allows you to define your own GitHub Actions steps instead of using an AI processor. Each step in the `steps` array follows standard GitHub Actions step syntax with `name`, `uses`/`run`, `with`, `env`, etc. This is useful for deterministic workflows that don't require AI processing.
 
     **Environment Variables Available to Custom Engines:**
-    
+
     Custom engine steps have access to the following environment variables:
-    
+
     - **`$GH_AW_PROMPT`**: Path to the generated prompt file (`/tmp/gh-aw/aw-prompts/prompt.txt`) containing the markdown content from the workflow. This file contains the natural language instructions that would normally be sent to an AI processor. Custom engines can read this file to access the workflow's markdown content programmatically.
     - **`$GH_AW_SAFE_OUTPUTS`**: Path to the safe outputs file (when safe-outputs are configured). Used for writing structured output that gets processed automatically.
     - **`$GH_AW_MAX_TURNS`**: Maximum number of turns/iterations (when max-turns is configured in engine config).
-    
+
     Example of accessing the prompt content:
     ```bash
     # Read the workflow prompt content
     cat $GH_AW_PROMPT
-    
+
     # Process the prompt content in a custom step
     - name: Process workflow instructions
       run: |
@@ -253,7 +253,7 @@ The YAML frontmatter supports these fields:
         log-level: debug                  # Optional: debug, info (default), warn, error
         args: ["--custom-arg", "value"]   # Optional: additional AWF arguments
     ```
-  
+
 - **`sandbox:`** - Sandbox configuration for AI engines (string or object)
   - String format: `"default"` (no sandbox), `"awf"` (Agent Workflow Firewall), `"srt"` or `"sandbox-runtime"` (Anthropic Sandbox Runtime)
   - Object format for full configuration:
@@ -703,7 +703,7 @@ cache:
     restore-keys: |
       node-modules-
   - key: build-cache-${{ github.sha }}
-    path: 
+    path:
       - dist
       - .cache
     restore-keys:
@@ -963,7 +963,7 @@ All other expressions are dissallowed.
 The `needs.activation.outputs.text` value provides automatically sanitized content based on the triggering event:
 
 - **Issues**: `title + "\n\n" + body`
-- **Pull Requests**: `title + "\n\n" + body`  
+- **Pull Requests**: `title + "\n\n" + body`
 - **Issue Comments**: `comment.body`
 - **PR Review Comments**: `comment.body`
 - **PR Reviews**: `review.body`
@@ -1163,7 +1163,7 @@ permissions:
 
 safe-outputs:
   create-issue:       # Automatic issue creation
-  add-comment:  # Automatic comment creation  
+  add-comment:  # Automatic comment creation
   create-pull-request: # Automatic PR creation
 ```
 
@@ -1437,7 +1437,7 @@ The `--start-date` and `--end-date` flags support delta time syntax for relative
 
 **Supported Time Units:**
 - **Days**: `-1d`, `-7d`
-- **Weeks**: `-1w`, `-4w` 
+- **Weeks**: `-1w`, `-4w`
 - **Months**: `-1mo`, `-6mo`
 - **Hours/Minutes**: `-12h`, `-30m` (for sub-day precision)
 - **Combinations**: `-1mo2w3d`, `-2w5d12h`
@@ -1447,7 +1447,7 @@ The `--start-date` and `--end-date` flags support delta time syntax for relative
 # Get runs from the last week
 gh aw logs --start-date -1w
 
-# Get runs up to yesterday  
+# Get runs up to yesterday
 gh aw logs --end-date -1d
 
 # Get runs from the last month
@@ -1502,7 +1502,7 @@ permissions:
 GitHub Agentic Workflows supports security scanning during compilation with `--actionlint`, `--zizmor`, and `--poutine` flags.
 
 **actionlint** - Lints GitHub Actions workflows and validates shell scripts with integrated shellcheck
-**zizmor** - Scans for security vulnerabilities, privilege escalation, and secret exposure  
+**zizmor** - Scans for security vulnerabilities, privilege escalation, and secret exposure
 **poutine** - Analyzes supply chain risks and third-party action usage
 
 ```bash
@@ -1559,7 +1559,7 @@ gh aw mcp list-tools github weekly-research
 
 This command is useful for:
 - **Discovering capabilities**: See what tools are available from each MCP server
-- **Workflow discovery**: Find which workflows use a specific MCP server  
+- **Workflow discovery**: Find which workflows use a specific MCP server
 - **Permission debugging**: Check which tools are allowed in your workflow configuration
 
 ## Compilation Process
@@ -1588,7 +1588,7 @@ Agentic workflows compile to GitHub Actions YAML:
 
 1. **Use descriptive workflow names** that clearly indicate purpose
 2. **Set appropriate timeouts** to prevent runaway costs
-3. **Include security notices** for workflows processing user content  
+3. **Include security notices** for workflows processing user content
 4. **Use the `imports:` field** in frontmatter for common patterns and security boilerplate
 5. **ALWAYS run `gh aw compile` after every change** to generate the GitHub Actions workflow (or `gh aw compile <workflow-id>` for specific workflows)
 6. **Review generated `.lock.yml`** files before deploying
@@ -1651,4 +1651,4 @@ gh aw logs <workflow-id>
 
 ### Documentation
 
-For complete CLI documentation, see: https://githubnext.github.io/gh-aw/setup/cli/
+For complete CLI documentation, see: https://githubnext.github.io/gh-aw/setup/cli/

docs/getting-started.md

@@ -950,10 +950,10 @@ By default, the SDK automatically manages the Copilot CLI process lifecycle, sta
 
 ### Running the CLI in Server Mode
 
-Start the CLI in server mode using the `--server` flag and optionally specify a port:
+Start the CLI in server mode using the `--headless` flag and optionally specify a port:
 
 ```bash
-copilot --server --port 4321
+copilot --headless --port 4321
 ```
 
 If you don't specify a port, the CLI will choose a random available port.

dotnet/README.md

@@ -126,7 +126,7 @@ Delete a session and its data from disk.
 
 ##### `GetForegroundSessionIdAsync(): Task<string?>`
 
-Get the ID of the session currently displayed in the TUI. Only available when connecting to a server running in TUI+server mode (`--interactive --server`).
+Get the ID of the session currently displayed in the TUI. Only available when connecting to a server running in TUI+server mode (`--ui-server`).
 
 ##### `SetForegroundSessionIdAsync(string sessionId): Task`
 
@@ -499,13 +499,13 @@ var session = await client.CreateSessionAsync(new SessionConfig
         // request.Question - The question to ask
         // request.Choices - Optional list of choices for multiple choice
         // request.AllowFreeform - Whether freeform input is allowed (default: true)
-        
+
         Console.WriteLine($"Agent asks: {request.Question}");
         if (request.Choices?.Count > 0)
         {
             Console.WriteLine($"Choices: {string.Join(", ", request.Choices)}");
         }
-        
+
         // Return the user's response
         return new UserInputResponse
         {
@@ -538,7 +538,7 @@ var session = await client.CreateSessionAsync(new SessionConfig
                 AdditionalContext = "Extra context for the model"
             };
         },
-        
+
         // Called after each tool execution
         OnPostToolUse = async (input, invocation) =>
         {
@@ -548,7 +548,7 @@ var session = await client.CreateSessionAsync(new SessionConfig
                 AdditionalContext = "Post-execution notes"
             };
         },
-        
+
         // Called when user submits a prompt
         OnUserPromptSubmitted = async (input, invocation) =>
         {
@@ -558,7 +558,7 @@ var session = await client.CreateSessionAsync(new SessionConfig
                 ModifiedPrompt = input.Prompt // Optionally modify the prompt
             };
         },
-        
+
         // Called when session starts
         OnSessionStart = async (input, invocation) =>
         {
@@ -568,14 +568,14 @@ var session = await client.CreateSessionAsync(new SessionConfig
                 AdditionalContext = "Session initialization context"
             };
         },
-        
+
         // Called when session ends
         OnSessionEnd = async (input, invocation) =>
         {
             Console.WriteLine($"Session ended: {input.Reason}");
             return null;
         },
-        
+
         // Called when an error occurs
         OnErrorOccurred = async (input, invocation) =>
         {

dotnet/src/Client.cs

@@ -673,7 +673,7 @@ public async Task<List<SessionMetadata>> ListSessionsAsync(CancellationToken can
     /// </summary>
     /// <remarks>
     /// This is only available when connecting to a server running in TUI+server mode
-    /// (--interactive --server).
+    /// (--ui-server).
     /// </remarks>
     /// <param name="cancellationToken">A token to cancel the operation.</param>
     /// <returns>The session ID, or null if no foreground session is set.</returns>
@@ -701,7 +701,7 @@ public async Task<List<SessionMetadata>> ListSessionsAsync(CancellationToken can
     /// </summary>
     /// <remarks>
     /// This is only available when connecting to a server running in TUI+server mode
-    /// (--interactive --server).
+    /// (--ui-server).
     /// </remarks>
     /// <param name="sessionId">The ID of the session to display in the TUI.</param>
     /// <param name="cancellationToken">A token to cancel the operation.</param>
@@ -875,7 +875,7 @@ private async Task VerifyProtocolVersionAsync(Connection connection, Cancellatio
             args.AddRange(options.CliArgs);
         }
 
-        args.AddRange(["--server", "--log-level", options.LogLevel]);
+        args.AddRange(["--headless", "--log-level", options.LogLevel]);
 
         if (options.UseStdio)
         {

go/client.go

@@ -61,24 +61,24 @@ import (
 //	}
 //	defer client.Stop()
 type Client struct {
-	options                  ClientOptions
-	process                  *exec.Cmd
-	client                   *JSONRPCClient
-	actualPort               int
-	actualHost               string
-	state                    ConnectionState
-	sessions                 map[string]*Session
-	sessionsMux              sync.Mutex
-	isExternalServer         bool
-	conn                     net.Conn // stores net.Conn for external TCP connections
-	useStdio                 bool     // resolved value from options
-	autoStart                bool     // resolved value from options
-	autoRestart              bool     // resolved value from options
-	modelsCache              []ModelInfo
-	modelsCacheMux           sync.Mutex
-	lifecycleHandlers        []SessionLifecycleHandler
-	typedLifecycleHandlers   map[SessionLifecycleEventType][]SessionLifecycleHandler
-	lifecycleHandlersMux     sync.Mutex
+	options                ClientOptions
+	process                *exec.Cmd
+	client                 *JSONRPCClient
+	actualPort             int
+	actualHost             string
+	state                  ConnectionState
+	sessions               map[string]*Session
+	sessionsMux            sync.Mutex
+	isExternalServer       bool
+	conn                   net.Conn // stores net.Conn for external TCP connections
+	useStdio               bool     // resolved value from options
+	autoStart              bool     // resolved value from options
+	autoRestart            bool     // resolved value from options
+	modelsCache            []ModelInfo
+	modelsCacheMux         sync.Mutex
+	lifecycleHandlers      []SessionLifecycleHandler
+	typedLifecycleHandlers map[SessionLifecycleEventType][]SessionLifecycleHandler
+	lifecycleHandlersMux   sync.Mutex
 }
 
 // NewClient creates a new Copilot CLI client with the given options.
@@ -915,7 +915,7 @@ func (c *Client) DeleteSession(sessionID string) error {
 // GetForegroundSessionID returns the ID of the session currently displayed in the TUI.
 //
 // This is only available when connecting to a server running in TUI+server mode
-// (--interactive --server). Returns nil if no foreground session is set.
+// (--ui-server). Returns nil if no foreground session is set.
 //
 // Example:
 //
@@ -958,7 +958,7 @@ func (c *Client) GetForegroundSessionID() (*string, error) {
 // SetForegroundSessionID requests the TUI to switch to displaying the specified session.
 //
 // This is only available when connecting to a server running in TUI+server mode
-// (--interactive --server).
+// (--ui-server).
 //
 // Example:
 //
@@ -1277,7 +1277,7 @@ func (c *Client) verifyProtocolVersion() error {
 // This spawns the CLI server as a subprocess using the configured transport
 // mode (stdio or TCP).
 func (c *Client) startCLIServer() error {
-	args := []string{"--server", "--log-level", c.options.LogLevel}
+	args := []string{"--headless", "--log-level", c.options.LogLevel}
 
 	// Choose transport mode
 	if c.useStdio {
@@ -1432,7 +1432,8 @@ func (c *Client) connectViaTcp() error {
 // setupNotificationHandler configures handlers for session events, tool calls, and permission requests.
 func (c *Client) setupNotificationHandler() {
 	c.client.SetNotificationHandler(func(method string, params map[string]any) {
-		if method == "session.event" {
+		switch method {
+		case "session.event":
 			// Extract sessionId and event
 			sessionID, ok := params["sessionId"].(string)
 			if !ok {
@@ -1458,7 +1459,7 @@ func (c *Client) setupNotificationHandler() {
 			if ok {
 				session.dispatchEvent(event)
 			}
-		} else if method == "session.lifecycle" {
+		case "session.lifecycle":
 			// Handle session lifecycle events
 			eventJSON, err := json.Marshal(params)
 			if err != nil {

nodejs/README.md

@@ -118,7 +118,7 @@ Delete a session and its data from disk.
 
 ##### `getForegroundSessionId(): Promise<string | undefined>`
 
-Get the ID of the session currently displayed in the TUI. Only available when connecting to a server running in TUI+server mode (`--interactive --server`).
+Get the ID of the session currently displayed in the TUI. Only available when connecting to a server running in TUI+server mode (`--ui-server`).
 
 ##### `setForegroundSessionId(sessionId: string): Promise<void>`
 

nodejs/src/client.ts

@@ -825,7 +825,7 @@ export class CopilotClient {
      * Gets the foreground session ID in TUI+server mode.
      *
      * This returns the ID of the session currently displayed in the TUI.
-     * Only available when connecting to a server running in TUI+server mode (--interactive --server).
+     * Only available when connecting to a server running in TUI+server mode (--ui-server).
      *
      * @returns A promise that resolves with the foreground session ID, or undefined if none
      * @throws Error if the client is not connected
@@ -851,7 +851,7 @@ export class CopilotClient {
      * Sets the foreground session in TUI+server mode.
      *
      * This requests the TUI to switch to displaying the specified session.
-     * Only available when connecting to a server running in TUI+server mode (--interactive --server).
+     * Only available when connecting to a server running in TUI+server mode (--ui-server).
      *
      * @param sessionId - The ID of the session to display in the TUI
      * @returns A promise that resolves when the session is switched
@@ -962,7 +962,7 @@ export class CopilotClient {
         return new Promise((resolve, reject) => {
             const args = [
                 ...this.options.cliArgs,
-                "--server",
+                "--headless",
                 "--log-level",
                 this.options.logLevel,
             ];