> For the complete documentation index, see [llms.txt](https://orbitron.gitbook.io/orbitron-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://orbitron.gitbook.io/orbitron-docs/user-guide/usage.md).

# Usage

Orbitron supports two primary modes of operation to accommodate different workflows and environments:

### **🔗 1. Interactive Mode**

Interactive Mode is Orbitron's **default operating environment**, allowing users to interact with AI in real time and perform tasks step by step.\
This mode is particularly suitable for **first-time users of Orbitron** or for **situations where complex tasks require real-time AI assistance**.

* **Step-by-step guidance:** The AI not only executes commands but also guides users through each stage.
* **Ideal for learning and exploration:** Enables experimentation with new cloud commands and workflows.
* **No need for predefined options:** Collects necessary information dynamically through dialogue during execution.

Example Usage:

```bash
# Run Orbitron
orbitron

# Specific a working directory
orbitron -c /path/to/project
```

This will launch Orbitron into an interactive terminal session.

<figure><img src="/files/jB92OsNMfFCSzaEBeuMe" alt=""><figcaption></figcaption></figure>

***

### 📋 2. Interactive with Context

Orbitron provides a built-in **memory file system** designed to store and manage project-specific or conversational context.

This enables the AI to remember information from previous sessions and deliver **consistent results** across repeated tasks.

***

#### 📁 `orbitron.md` – The Memory File

Orbitron's context is managed through Supabase. You can also manage context locally by creating an `orbitron.md` file in your project directory.

**📝 Purpose of Context:**

* Stores your **project goals**, **configurations**, **key decisions**, and **summary of AI conversations**.
* Managed through Supabase or a local file (`orbitron.md`).
* Enhances **context awareness** in subsequent interactions with the AI.

> 💡 **Note**: The context management method may vary depending on your configuration. By default it is managed through Supabase, but local file-based management is also supported.

This allows Orbitron to "remember" your work and respond accordingly.

***

#### ⚙️ Usage: Creating Context Files

You can quickly generate a new `orbitron.md` file from your active context using the following method:

1. **Press `Ctrl + K`** or enter `/context` to open the context selection panel.
2. Choose the desired context from the **Orbitron Context Manager**.
3. Orbitron will create or update the `orbitron.md` file with the selected memory.

> 💡 Once created, all subsequent commands and conversations will reference the selected context automatically.

***

#### 🔍 Context Management Commands

Orbitron provides several CLI commands to help you view, filter, and manage stored conversational or project contexts. These contexts serve as memory anchors for the AI, enabling it to provide tailored, context-aware assistance.

| Command                        | Description                                    | Example Usage                                                                                 |
| ------------------------------ | ---------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `/context`                     | View all available contexts                    | `/context`                                                                                    |
| `/context:tag [tag]`           | Display only contexts linked to a specific tag | <p><code>/context:tag cloud</code></p><p><code>/context:tag security</code></p>               |
| `/context:category [category]` | Filter and display contexts by category        | <p><code>/context:category production</code></p><p><code>/context:category staging</code></p> |

#### `/context:tag [tag]`

* Use this when you want to quickly retrieve context related to a particular topic (e.g., `aws`, `devops`, `cost-optimization`).

#### `/context:category [category]`

* Categories can represent logical groupings such as `development`, `production`, `experiments`, etc.

These commands help narrow the scope of the context memory Orbitron uses when responding to your queries. Once selected, the associated memory is loaded into the current session.

***

#### ✅ Benefits of Context-Aware Interaction

* **Persistent memory:** Context is saved and maintained across sessions.
* **Accurate responses:** The AI can tailor answers based on project-specific information.
* **Editable:** Users can manually update context information in `orbitron.md`.
* **Multi-context support:** Contexts can be switched as needed using the manager.

> 💡 Tip: When working on multiple projects simultaneously, it’s more efficient to maintain a separate `orbitron.md` file for each project.

***

### ⛓️‍💥 3. **Non-Interactive Mode**

Orbitron supports **non-interactive mode** for users who prefer automation, scripting, or minimal UI interaction.

In this mode, you can issue questions or commands directly via the CLI and receive responses immediately — without entering an interactive terminal session.

* All required options must be passed via CLI flags or config files
* Enables full automation and batch processing
* Ideal for headless environments and pipelines

#### 🛠 How to Use

You can invoke Orbitron non-interactively using the `-p` (prompt) flag followed by your question or command:

**🔹 Basic Execution**

```bash
orbitron -p "How do I list all EC2 instances?"
```

This sends the question to the AI engine and prints the response to standard output.

**🔹 Quiet Mode (Clean Output)**

```bash
orbitron -p "How do I list all EC2 instances?" -q
```

This hides meta information such as timestamps, headers, or progress indicators, providing a cleaner response — ideal for piping or logging.

**🔹 Output in JSON Format**

```bash
orbitron -p "How do I list all EC2 instances?" -q -f json
```

This returns the AI response wrapped in a structured JSON object, suitable for programmatic parsing or integration.

***

#### 📤 Supported Output Formats

| Format | Description                                |
| ------ | ------------------------------------------ |
| `text` | Plain text output (default)                |
| `json` | JSON-wrapped output with structured fields |

> You can specify the output format using `-f text` or `-f json`.

***

#### ✅ Example Use Cases

* **Shell scripting**:

  ```bash
  orbitron -p "Generate a bash script to back up an S3 bucket" -q > backup.sh
  ```
* **CI/CD integration**:

  ```bash
  orbitron -p "Summarize terraform plan output" -q -f json | jq '.response'
  ```
* **Chat-free automation**: Use `-q` with `-f` to extract only relevant information and suppress all UI/UX prompts.

***

### 🚩 Command-Line Flags

The following flags are available when using **Orbitron in non-interactive mode**. These options allow you to customize execution behavior, control output, and integrate Orbitron into scripts or automation pipelines.

<table><thead><tr><th width="170.125">Flag</th><th width="89.94921875">Alias</th><th width="119.8984375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>--cwd</code></td><td><code>-c</code></td><td><code>string</code></td><td>Sets the current working directory. Useful for resolving relative paths or running project-specific commands.</td></tr><tr><td><code>--debug</code></td><td><code>-d</code></td><td><code>boolean</code></td><td>Enables debug mode with verbose output for troubleshooting.</td></tr><tr><td><code>--help</code></td><td><code>-h</code></td><td><code>boolean</code></td><td>Displays help information and usage instructions.</td></tr><tr><td><code>--output-format</code></td><td><code>-f</code></td><td><code>string</code></td><td>Specifies output format: <code>text</code> (default) or <code>json</code>.</td></tr><tr><td><code>--prompt</code></td><td><code>-p</code></td><td><code>string</code></td><td>Executes a single prompt in non-interactive mode.</td></tr><tr><td><code>--quiet</code></td><td><code>-q</code></td><td><code>boolean</code></td><td>Suppresses spinner and additional terminal UI elements. Ideal for clean or machine-parsable output.</td></tr><tr><td><code>--version</code></td><td><code>-v</code></td><td><code>boolean</code></td><td>Displays the current version of Orbitron.</td></tr><tr><td><code>--access-token</code></td><td></td><td><code>string</code></td><td>Access token for programmatic authentication. Must be used together with <code>--refresh-token</code>.</td></tr><tr><td><code>--refresh-token</code></td><td></td><td><code>string</code></td><td>Refresh token for programmatic authentication. Must be used together with <code>--access-token</code>.</td></tr></tbody></table>

#### ✅ Example Usages

**📋 Basic prompt**

```bash
orbitron -p "Summarize the latest Terraform plan"
```

**🧼 Clean output (quiet mode)**

```bash
orbitron -p "List all S3 buckets" -q
```

**🧾 JSON output for automation**

```bash
orbitron -p "Check GCP billing" -q -f json
```

**📁 Custom working directory**

```bash
orbitron -p "Scan this directory for secrets" -c ./infra/
```

**🐞 Enable debugging**

```bash
orbitron -p "Diagnose my ECS deployment" -d
```

> ℹ️ Tip: You can combine multiple flags for full control in CI/CD pipelines or scripted workflows.

***

### 🎯 Summary

| Mode                         | Description                                                                                 | Use Cases                                                        |
| ---------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| **Interactive Mode**         | Launches a terminal session with live AI interaction.                                       | First-time users, exploratory tasks, manual prompts              |
| **Interactive with Context** | Interactive session with loaded project memory (`orbitron.md`) for context-aware responses. | Ongoing projects, structured workflows, assistant-led automation |
| **Non-Interactive Mode**     | Executes a single command or question via CLI and returns output immediately.               | Automation scripts, CI/CD pipelines, fast one-off queries        |

***

#### ⚠️ Notes

* `orbitron.md` contains important context information. Be careful not to delete or modify it unintentionally.
* In non-interactive mode, all options must be specified precisely; typos or omissions may cause errors.
* When using multiple contexts, always verify the currently loaded context before executing tasks.