Noora Documentation

The TerminalText API allows you to apply semantic formatting to terminal output. Instead of hardcoding colors, you use semantic components that adapt to the user's terminal capabilities and theme.

Note: It is recommended to use this API sparingly. Prefer using built-in TerminalText components for standard output whenever possible, and only use custom TerminalText strings when the specific semantics of your text are not covered by existing components.

The Selectable Table component is interactive and supports the following keyboard controls:

Use the .success() method on a Noora instance to display a success message to the user. You can provide a simple string message or a more complex .alert configuration that includes a list of recommended next steps.

// Simple success message
Noora().success("The project has been successfully initialized")

// Success alert with next steps
Noora().success(.alert("The project has been successfully initialized", nextSteps: [
  "Run \(.command("tuist registry setup")) to speed up package resolution.",
  "Cache your project targets as binaries with \(.command("tuist cache")).",
]))

The collapsibleStep component is used to represent long-running tasks that stream output. It displays a limited number of recent output lines while the task is running and automatically collapses the output upon completion. This prevents the user from losing context while keeping the interface clean. It supports both interactive and non-interactive modes.

try await Noora().collapsibleStep(
    title: "Build",
    successMessage: "Build succeeded",
    errorMessage: "Build failed",
    visibleLines: 3
) { progress in
    try await xcodebuild() { progress($0) }
}

Noora provides several categories of components for building terminal interfaces:

• Prompts: Interactive user input (yes/no choices, text input, single choice selection).
• Alerts: Status messages (success, warning, error notifications).
• Progress: Visual progress indicators (progress bars, step indicators).
• Text Styling: Consistent typography and formatting.

To use them, import Noora and instantiate the Noora() object to access the component methods.

import Noora

Noora().yesOrNoChoicePrompt(
  title: "Authentication",
  question: "Would you like to authenticate?",
  defaultAnswer: true,
  description: "Authentication is required to use some CLI features."
)

To use Noora, first create an instance of Noora. All available UI components are accessed as methods on this instance. For example, you can use yesOrNoChoicePrompt to create a boolean selection prompt.

import Noora

Noora().yesOrNoChoicePrompt(
  title: "Authentication",
  question: "Would you like to authenticate?",
  defaultAnswer: true,
  description: "Authentication is required to use some CLI features."
)

To use Noora in your Swift project, add it as a dependency in your Package.swift file using the following URL and version requirement:

.package(url: "https://github.com/tuist/Noora", .upToNextMajor(from: "0.15.0"))

The progressStep component represents a step in a command's execution. It tracks the time taken to complete a task and can display different messages based on the outcome (success or failure). It supports both interactive modes (with a spinner and message updates) and non-interactive modes.

let graph = try await Noora().progressStep(
    message: "Processing the graph",
    successMessage: "Project graph processed",
    errorMessage: "Failed to process the project graph"
) { updateMessage in
    // An example of an asynchronous task.
    let graph = try await loadGraph()

    // You can use updateMessage to update the progress step message.
    updateMessage("Analyzing the graph")

    // Another asynchronous task.
    try await analyzeGraph(graph)

    return graph
}