feat: Update CLI reference for azd app run command and add new flags (#117)

- Changed example command for `azd app run` to include `--force` and added a new example for `--runtime aspire`.
- Updated the flags section to include descriptions for the new `--force` flag.
- Added additional example commands to demonstrate usage.

---

chore: Enhance "What's New" section with v0.11.0 updates

- Added new article for version v0.11.0 with features, fixes, and enhancements.
- Removed outdated v0.9.0 article to streamline the changelog.

---

feat: Introduce Environment Name Display feature in dashboard

- Created a new specification for displaying the current Azure environment name in the dashboard header.
- Recommended placement and visual design for the environment name badge.
- Updated backend API to include environment name and modified frontend components to display it.

---

feat: Implement EnvironmentBadge component for displaying environment name

- Added `EnvironmentBadge` component to show the Azure environment name in the header.
- Ensured the badge is responsive and hidden on mobile devices.
- Integrated the badge into the header with appropriate styling and accessibility features.

Author: jongio

cli/dashboard/design/features/environment-name-display.md

@@ -1,6 +1,7 @@
 import { useState, useEffect, useMemo } from 'react'
 import { useServicesContext } from '@/contexts/ServicesContext'
 import { useHealthStream } from '@/hooks/useHealthStream'
+import { useCodespaceEnv } from '@/hooks/useCodespaceEnv'
 import { App as DashboardApp } from '@/components/App'
 import { BackendConnectionContext } from '@/hooks/useBackendConnection'
 import type { HealthCheckResult } from '@/types'
@@ -9,6 +10,9 @@ function App() {
   const [projectName, setProjectName] = useState<string>('')
   const { services } = useServicesContext()
 
+  // Environment info (includes Azure environment name)
+  const { environmentName } = useCodespaceEnv()
+  
   // Real-time health monitoring
   const { 
     healthReport, 
@@ -74,6 +78,7 @@ function App() {
         healthMap={healthMap}
         healthError={healthError}
         healthReconnect={healthReconnect}
+        environmentName={environmentName}
       />
     </BackendConnectionContext.Provider>
   )

cli/dashboard/src/App.tsx

@@ -37,6 +37,8 @@ export interface AppProps {
   healthError?: string | null
   /** Function to manually reconnect */
   healthReconnect?: () => void
+  /** Azure environment name to display in header */
+  environmentName?: string
   /** Additional class names */
   className?: string
 }
@@ -133,6 +135,7 @@ export function App({
   healthReport,
   healthMap,
   healthError,
+  environmentName,
   className,
 }: AppProps) {
   const [activeView, setActiveView] = React.useState<View>(getInitialView)
@@ -358,6 +361,7 @@ export function App({
         services={services}
         hasActiveErrors={false}
         loading={!connected && services.length === 0}
+        environmentName={environmentName}
       />
 
       {/* Settings Dialog */}

cli/dashboard/src/components/App.tsx

@@ -0,0 +1,49 @@
+/**
+ * EnvironmentBadge - Displays Azure environment name in the header
+ * Shows a subtle badge with the environment name (e.g., "· dev")
+ * Hidden on mobile devices (<640px)
+ */
+import { cn } from '@/lib/utils'
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface EnvironmentBadgeProps {
+  /** Azure environment name to display */
+  environmentName?: string
+  /** Additional class names */
+  className?: string
+}
+
+// =============================================================================
+// EnvironmentBadge Component
+// =============================================================================
+
+export function EnvironmentBadge({ 
+  environmentName, 
+  className 
+}: EnvironmentBadgeProps) {
+  // Don't render if no environment name
+  if (!environmentName) {
+    return null
+  }
+
+  return (
+    <span
+      className={cn(
+        'hidden sm:inline-flex items-center gap-1.5',
+        'px-2 py-[3px] rounded',
+        'text-xs font-medium leading-none',
+        'bg-slate-100 dark:bg-slate-800',
+        'text-slate-500 dark:text-slate-400',
+        className
+      )}
+      aria-label={`Environment: ${environmentName}`}
+      role="status"
+    >
+      <span className="text-cyan-500 dark:text-cyan-400 leading-none" aria-hidden="true">·</span>
+      <span className="leading-none">{environmentName}</span>
+    </span>
+  )
+}

cli/dashboard/src/components/EnvironmentBadge.tsx

@@ -16,6 +16,7 @@ import { cn } from '@/lib/utils'
 import { ThemeToggle } from './ThemeToggle'
 import { HealthPill, ConnectionStatus } from './StatusIndicator'
 import { ServiceStatusCard } from './ServiceStatusCard'
+import { EnvironmentBadge } from './EnvironmentBadge'
 import type { HealthSummary, Service } from '@/types'
 
 // =============================================================================
@@ -52,6 +53,8 @@ export interface HeaderProps {
   hasActiveErrors?: boolean
   /** Whether dashboard is loading */
   loading?: boolean
+  /** Azure environment name to display */
+  environmentName?: string
   /** Additional class names */
   className?: string
 }
@@ -124,6 +127,7 @@ export function Header({
   services,
   hasActiveErrors = false,
   loading = false,
+  environmentName,
   className,
 }: HeaderProps) {
   const navRef = React.useRef<HTMLDivElement>(null)
@@ -201,6 +205,7 @@ export function Header({
         <h1 className="text-lg font-semibold text-slate-900 dark:text-slate-100 truncate tracking-tight">
           {projectName || 'Dashboard'}
         </h1>
+        <EnvironmentBadge environmentName={environmentName} />
         {connected && (
           <span className="relative flex h-2 w-2" aria-hidden="true">
             <span className="animate-ping absolute inline-flex h-full w-full rounded-full bg-emerald-400 opacity-75"></span>

cli/dashboard/src/components/Header.tsx

@@ -37,6 +37,10 @@ export {
 } from './StatusIndicator'
 export type { EffectiveStatus } from './StatusIndicator'
 
+// Environment Badge
+export { EnvironmentBadge } from './EnvironmentBadge'
+export type { EnvironmentBadgeProps } from './EnvironmentBadge'
+
 // Console View
 export { ConsoleView } from './ConsoleView'
 export type { ConsoleViewProps } from './ConsoleView'

cli/dashboard/src/components/index.ts

@@ -16,6 +16,8 @@ export interface UseCodespaceEnvReturn {
   isCodespace: boolean
   /** Codespace configuration (null if not in Codespace or loading) */
   config: CodespaceConfig | null
+  /** Azure environment name (if available) */
+  environmentName?: string
   /** Whether the environment info is still loading */
   loading: boolean
   /** Error message if fetch failed */
@@ -98,6 +100,11 @@ export function useCodespaceEnv(): UseCodespaceEnvReturn {
     const cached = getCachedEnv()
     return cached?.codespace ?? null
   })
+  const [environmentName, setEnvironmentName] = useState<string | undefined>(() => {
+    // Initialize from cache if available
+    const cached = getCachedEnv()
+    return cached?.environmentName
+  })
   const [loading, setLoading] = useState<boolean>(() => {
     // Skip loading if we have cached data
     return getCachedEnv() === null
@@ -121,6 +128,7 @@ export function useCodespaceEnv(): UseCodespaceEnvReturn {
       setCachedEnv(data)
 
       setConfig(data.codespace)
+      setEnvironmentName(data.environmentName)
     } catch (err) {
       const message = err instanceof Error ? err.message : 'Unknown error'
       setError(message)
@@ -151,6 +159,7 @@ export function useCodespaceEnv(): UseCodespaceEnvReturn {
   return {
     isCodespace: config?.enabled ?? false,
     config,
+    environmentName,
     loading,
     error,
     refresh,

cli/dashboard/src/hooks/useCodespaceEnv.tsx

@@ -21,6 +21,7 @@ export interface CodespaceConfig {
 
 export interface EnvironmentInfo {
   codespace: CodespaceConfig
+  environmentName?: string
 }
 
 // =============================================================================

cli/dashboard/src/lib/codespace-utils.ts

@@ -39,6 +39,7 @@ These flags are available for all commands:
 | `--debug` | | bool | `false` | Enable debug logging |
 | `--structured-logs` | | bool | `false` | Enable structured JSON logging to stderr |
 | `--cwd` | `-C` | string | `""` | Sets the current working directory |
+| `--environment` | `-e` | string | `""` | The name of the environment to use |
 
 **Examples:**
 ```bash
@@ -53,6 +54,9 @@ azd app deps --structured-logs
 
 # Run from a specific project directory
 azd app run --cwd ./my-project
+
+# Use a specific environment
+azd app run --environment production
 ```
 
 ## Commands Overview
@@ -73,7 +77,6 @@ azd app run --cwd ./my-project
 | `mcp` | Model Context Protocol server for AI assistant integration | [→ Full Spec](commands/mcp.md) |
 | `notifications` | Manage process notifications for service state changes | [→ Full Spec](commands/notifications.md) |
 | `version` | Show version information | [→ Full Spec](commands/version.md) |
-| `completion` | Generate shell autocompletion scripts | [→ Full Spec](commands/completion.md) |
 | `listen` | Extension framework integration (hidden, used by azd internally) | [→ Full Spec](commands/listen.md) |
 
 ---
@@ -293,6 +296,9 @@ azd app run --env-file .env.local
 
 # Combine multiple flags
 azd app run -s web -v --runtime aspire
+
+# Force clean dependency reinstall before running
+azd app run --force
 ```
 
 ### Flags
@@ -305,6 +311,7 @@ azd app run -s web -v --runtime aspire
 | `--verbose` | `-v` | bool | `false` | Enable verbose logging |
 | `--dry-run` | | bool | `false` | Show what would be run without starting services |
 | `--restart-containers` | | bool | `false` | Restart containers even if they are already running |
+| `--force` | `-f` | bool | `false` | Force clean dependency reinstall (passes --force to deps) |
 | `--web` | `-w` | bool | `false` | Open dashboard in browser |
 
 ### Runtime Modes

cli/docs/cli-reference.md

@@ -47,13 +47,17 @@ func (s *Server) handleGetEnvironment(w http.ResponseWriter, r *http.Request) {
 	// Only in browser-based Codespace do we need to transform localhost URLs
 	isVsCodeDesktop := runningOnVsCodeDesktop()
 
+	// Get Azure environment name if available
+	azureEnvName := os.Getenv("AZURE_ENV_NAME")
+
 	response := map[string]interface{}{
 		"codespace": map[string]interface{}{
 			"enabled":         codespaceName != "",
 			"name":            codespaceName,
 			"domain":          codespacePortDomain,
 			"isVsCodeDesktop": isVsCodeDesktop,
 		},
+		"environmentName": azureEnvName,
 	}
 
 	WriteJSONSuccess(w, response)