aura

command module
v0.0.0-beta Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 30, 2026 License: MIT Imports: 6 Imported by: 0

README

aura logo

aura

Agentic coding CLI

Aura in Action

aura is a terminal-based coding assistant that connects to local or remote LLMs. Define agents, tools, modes, and guardrails as YAML and Markdown files.

Install

go install github.com/idelchi/aura@latest

Usage

# Initialize configuration
aura init

# Install recommended plugins
aura plugins add --subpath plugins/injectors https://github.com/idelchi/aura
aura plugins add --subpath plugins/tools https://github.com/idelchi/aura

# Start interactive session
aura

# One-off prompt
aura run "explain this codebase"

# List available models
aura models

Providers

Provider API Notes
Ollama Native Ollama API Local models, embedding, thinking, vision
LlamaCPP OpenAI-compatible Local llama.cpp server; also used for whisper and kokoro
OpenRouter OpenRouter API Cloud models, token auth
OpenAI OpenAI Responses API Any /v1/responses endpoint
Anthropic Native Anthropic Messages API Claude models, thinking, vision
Google Google Gemini API Gemini models, thinking, vision, embeddings
Copilot GitHub Copilot (dual-protocol) GPT + Claude via Copilot subscription
Codex OpenAI Plus (Responses API) ChatGPT Plus/Pro subscription

Commands

aura              Interactive assistant (default)
aura run          Execute prompts non-interactively (inline or stdin)
aura mcp          List configured MCP servers and their tools
aura tasks        Manage and run scheduled tasks (list, show, run)
aura models       List available models
aura tools        List, inspect, or execute tools
aura query        Embedding-based search across the codebase
aura vision       Analyze an image or PDF via a vision-capable LLM
aura transcribe   Transcribe an audio file to text
aura speak        Convert text to speech audio
aura plugins      Manage plugins (list, show, add, remove, update)
aura skills       Manage skills (list, show, add, remove, update)
aura init         Initialize a default aura configuration
aura login        Authenticate with an OAuth provider (device code flow)
aura web          Start browser-based UI

Configuration

Everything lives under .aura/:

.aura/
├── config/
│   ├── agents/       # Agent definitions (model, provider, prompt, tool filters)
│   ├── commands/     # Custom slash commands (Markdown + YAML frontmatter)
│   ├── features/     # Feature configs (compaction, thinking, tools, vision, stt, tts, search, guardrail, estimation, subagent, plugins, mcp, sandbox, title)
│   ├── hooks/        # Shell hooks that run before/after tool execution
│   ├── lsp/          # Language server definitions for diagnostics
│   ├── modes/        # Mode definitions (tool availability, landlock restrictions, tool policy)
│   ├── mcp/          # MCP server definitions
│   ├── prompts/      # System prompts (referenced by agents)
│   ├── providers/    # Provider configs (ollama, llamacpp, openrouter, openai, anthropic, google, copilot, codex)
│   ├── rules/        # Persistent approval rules (created on-demand when approvals are saved)
│   ├── sandbox/      # Landlock restrictions
│   ├── tasks/        # Scheduled task definitions
│   └── tools/        # Optional tool text overrides (any tool type)
├── plugins/          # Go plugins (recursive discovery, organize into subdirs freely)
├── skills/           # LLM-invocable skills (Markdown + YAML frontmatter)
├── sessions/         # Saved sessions (JSON snapshots)
├── embeddings/       # Embeddings index (created on-demand when embeddings search is used)
└── memory/           # Persistent key-value memory files

Run aura init to scaffold the default configuration. Every file is meant to be edited.

Flags 
Flags:
      --agent string            The agent to use
      --auto                    Enable auto mode (continue while TODOs are pending or in-progress)
      --config strings          Configuration directories to merge (left-to-right, last wins)
  -c, --continue                Resume the most recent session
      --debug                   Enable debug logging
      --dry string              Dry-run mode: "render" (print and exit) or "noop" (run with noop provider)
  -e, --env-file strings        Environment files to load (default [secrets.env])
      --exclude-mcps strings     Glob patterns for MCP servers to skip (e.g. "portainer")
      --exclude-tools strings   Glob patterns for tools to exclude (e.g. "Bash,Patch")
      --experiments             Enable experimental features
      --home string             Global config home (~/.aura); set to empty to disable
      --include-mcps strings     Glob patterns for MCP servers to connect (e.g. "context7,git*")
      --include-tools strings   Glob patterns for tools to include (e.g. "Read,Glob,Rg")
      --max-steps int           Maximum tool-use iterations (overrides config)
      --token-budget int        Cumulative token limit (overrides config)
      --mode string             Starting mode (overrides agent config)
      --system string           System prompt (overrides agent config)
  -m, --model string            Model name (overrides agent config)
  -o, --output string           Mirror all output to file
      --provider string         LLM provider (overrides agent config)
      --resume string           Resume a saved session by ID prefix
      --providers strings       Limit to these providers (filters model listings and discards non-matching agents)
      --print                   Print loaded config summary and exit
      --print-env               Print resolved settings as AURA_* environment variables and exit
      --set KEY=value           Set template variables (KEY=value, repeatable)
  -s, --show                    Show the configuration and exit
      --simple                  Use simple readline-based TUI
      --think string            Thinking level (off, on, low, medium, high, overrides agent config)
  -v, --version                 version for aura
  -w, --workdir string          Working directory for tool execution and path resolution
      --without-plugins         Disable Go plugins
      --unsafe-plugins          Allow plugins to use os/exec and other restricted imports

All flags can be set via environment variables with the AURA_ prefix (e.g. AURA_AGENT=high, AURA_MODEL=llama3:8b, AURA_DEBUG=1). Use aura --print-env to see all resolved settings.

Contributing

See CONTRIBUTING.md for build instructions, testing, code style, and links to the developer documentation.

Documentation

Overview

Aura is an agentic coding CLI assistant.

Usage: 

aura [command] [flags]

Use "aura --help" for more information.

Source Files

View all Source files

Directories

Path Synopsis
internal
agent
Package agent provides the Agent type which represents a running LLM agent instance.
 Package agent provides the Agent type which represents a running LLM agent instance.
assistant
Package assistant manages AI conversations with configurable models, providers, and tool execution.
 Package assistant manages AI conversations with configurable models, providers, and tool execution.
chunker
Package chunker splits file content into overlapping token-limited chunks for embedding-based search.
 Package chunker splits file content into overlapping token-limited chunks for embedding-based search.
cli
Package cli provides the urfave/cli v3 application builder, command tree, and global flag configuration.
 Package cli provides the urfave/cli v3 application builder, command tree, and global flag configuration.
cli/core
Package core provides shared CLI infrastructure: global flags, session lifecycle, assistant wiring, tool execution, and MCP server connections.
 Package core provides shared CLI infrastructure: global flags, session lifecycle, assistant wiring, tool execution, and MCP server connections.
cli/init
Package initialize scaffolds a default aura configuration directory by extracting embedded configuration files.
 Package initialize scaffolds a default aura configuration directory by extracting embedded configuration files.
cli/login
Package login implements OAuth device code authentication for cloud providers.
 Package login implements OAuth device code authentication for cloud providers.
cli/mcp
Package mcp lists configured MCP servers and their tools.
 Package mcp lists configured MCP servers and their tools.
cli/models
Package models lists available LLM models from configured providers.
 Package models lists available LLM models from configured providers.
cli/plugins
Package plugins manages Go plugin lifecycle: list, show, add, update, and remove.
 Package plugins manages Go plugin lifecycle: list, show, add, update, and remove.
cli/query
Package query runs embedding-based search across the codebase.
 Package query runs embedding-based search across the codebase.
cli/run
Package run executes prompts non-interactively.
 Package run executes prompts non-interactively.
cli/skills
Package skills manages LLM-invocable skill lifecycle: list, show, add, update, and remove.
 Package skills manages LLM-invocable skill lifecycle: list, show, add, update, and remove.
cli/speak
Package speak converts text to speech audio via a configured provider.
 Package speak converts text to speech audio via a configured provider.
cli/tasks
Package tasks manages and runs scheduled tasks.
 Package tasks manages and runs scheduled tasks.
cli/tools
Package tools lists, inspects, and executes tools.
 Package tools lists, inspects, and executes tools.
cli/transcribe
Package transcribe converts audio files to text via a configured provider.
 Package transcribe converts audio files to text via a configured provider.
cli/vision
Package vision analyzes images or PDFs via a vision-capable LLM.
 Package vision analyzes images or PDFs via a vision-capable LLM.
cli/web
Package web starts the browser-based UI server.
 Package web starts the browser-based UI server.
condition
Package condition provides shared condition evaluation for /assert and custom injectors.
 Package condition provides shared condition evaluation for /assert and custom injectors.
config
Package config manages agent configuration including modes, systems, providers, and agent definitions.
 Package config manages agent configuration including modes, systems, providers, and agent definitions.
config/inherit
Package inherit provides struct-level config inheritance with DAG resolution.
 Package inherit provides struct-level config inheritance with DAG resolution.
config/merge
Package merge provides the canonical struct merge function for config inheritance and overlay.
 Package merge provides the canonical struct merge function for config inheritance and overlay.
conversation
Package conversation manages message history and emits events for LLM interactions.
 Package conversation manages message history and emits events for LLM interactions.
debug
Package debug provides a file-based debug logger activated by AURA_DEBUG=1.
 Package debug provides a file-based debug logger activated by AURA_DEBUG=1.
diffpreview
Package diffpreview generates unified diff strings for file modifications.
 Package diffpreview generates unified diff strings for file modifications.
directive
Package directive parses user input for inline directives like @Image, @File, and @Bash.
 Package directive parses user input for inline directives like @Image, @File, and @Bash.
embedder
Package embedder manages embedding generation and vector storage using chromem-go as an in-process persistent vector database.
 Package embedder manages embedding generation and vector storage using chromem-go as an in-process persistent vector database.
hooks
Package hooks provides user-configurable shell hooks that run before and after LLM tool calls.
 Package hooks provides user-configurable shell hooks that run before and after LLM tool calls.
indexer
Package indexer coordinates file walking, embedding, querying with deduplication and optional reranking for embedding-based search.
 Package indexer coordinates file walking, embedding, querying with deduplication and optional reranking for embedding-based search.
injector
Package injector provides the message injection system for synthetic conversation guidance.
 Package injector provides the message injection system for synthetic conversation guidance.
lsp
Package lsp provides Language Server Protocol integration for real-time diagnostics.
 Package lsp provides Language Server Protocol integration for real-time diagnostics.
mcp
Package mcp provides Model Context Protocol client connections and tool registration.
 Package mcp provides Model Context Protocol client connections and tool registration.
mirror
Package mirror duplicates os.Stdout and os.Stderr to a file.
 Package mirror duplicates os.Stdout and os.Stderr to a file.
plugins
Package plugins provides Yaegi-based Go plugin loading for conversation hooks.
 Package plugins provides Yaegi-based Go plugin loading for conversation hooks.
prompts
Package prompts provides template-based prompt management for agent configurations.
 Package prompts provides template-based prompt management for agent configurations.
providers
Package providers bridges internal config with the public provider implementations.
 Package providers bridges internal config with the public provider implementations.
session
Package session provides conversation persistence with save, resume, and fork capabilities.
 Package session provides conversation persistence with save, resume, and fork capabilities.
slash
Package slash provides slash command registry and dispatch for interactive commands.
 Package slash provides slash command registry and dispatch for interactive commands.
slash/commands
Package commands provides built-in slash command implementations.
 Package commands provides built-in slash command implementations.
snapshot
Package snapshot provides automatic working tree snapshots using git plumbing.
 Package snapshot provides automatic working tree snapshots using git plumbing.
spintext
Package spintext provides randomized loading messages for UI spinners.
 Package spintext provides randomized loading messages for UI spinners.
stats
Package stats tracks session-level metrics for the assistant.
 Package stats tracks session-level metrics for the assistant.
subagent
Package subagent provides a mini tool loop for spawning one-shot subagents with isolated conversation context and a restricted tool set.
 Package subagent provides a mini tool loop for spawning one-shot subagents with isolated conversation context and a restricted tool set.
task
Package task provides scheduled task definitions, schedule parsing, and a scheduler.
 Package task provides scheduled task definitions, schedule parsing, and a scheduler.
tmpl
Package tmpl provides Go template expansion with sprig functions for YAML-based command sequences.
 Package tmpl provides Go template expansion with sprig functions for YAML-based command sequences.
todo
Package todo manages a list of tasks with status tracking.
 Package todo manages a list of tasks with status tracking.
tools
Package tools provides the base set of assistant tools for file operations and command execution.
 Package tools provides the base set of assistant tools for file operations and command execution.
tools/ask
Package ask provides a tool for the LLM to ask the user questions mid-execution.
 Package ask provides a tool for the LLM to ask the user questions mid-execution.
tools/bash
Package bash provides shell command execution using mvdan/sh interpreter.
 Package bash provides shell command execution using mvdan/sh interpreter.
tools/batch
Package batch provides a meta-tool that executes multiple independent tool calls concurrently.
 Package batch provides a meta-tool that executes multiple independent tool calls concurrently.
tools/done
Package done provides a tool for the LLM to explicitly signal task completion.
 Package done provides a tool for the LLM to explicitly signal task completion.
tools/filetime
Package filetime tracks file read operations to enforce "read before edit" semantics.
 Package filetime tracks file read operations to enforce "read before edit" semantics.
tools/glob
Package glob provides file pattern matching using doublestar glob.
 Package glob provides file pattern matching using doublestar glob.
tools/loadtools
Package loadtools provides a meta-tool for on-demand loading of deferred tool schemas.
 Package loadtools provides a meta-tool for on-demand loading of deferred tool schemas.
tools/ls
Package ls provides directory listing operations.
 Package ls provides directory listing operations.
tools/memory
Package memory provides shared helpers for persistent key-value memory storage tools.
 Package memory provides shared helpers for persistent key-value memory storage tools.
tools/memory/read
Package read provides the MemoryRead tool for reading persistent memory entries.
 Package read provides the MemoryRead tool for reading persistent memory entries.
tools/memory/write
Package write provides the MemoryWrite tool for persisting memory entries.
 Package write provides the MemoryWrite tool for persisting memory entries.
tools/mkdir
Package mkdir provides directory creation operations.
 Package mkdir provides directory creation operations.
tools/patch
Package patch provides file patching operations using a context-aware diff format.
 Package patch provides file patching operations using a context-aware diff format.
tools/query
Package query provides a tool for embedding-based code search.
 Package query provides a tool for embedding-based code search.
tools/read
Package read provides file reading operations with line enumeration and range support.
 Package read provides file reading operations with line enumeration and range support.
tools/ripgrep
Package ripgrep provides regex search through files using ripgrep.
 Package ripgrep provides regex search through files using ripgrep.
tools/skill
Package skill provides a meta-tool for LLM-invocable skills with progressive disclosure.
 Package skill provides a meta-tool for LLM-invocable skills with progressive disclosure.
tools/speak
Package speak provides a tool for text-to-speech synthesis.
 Package speak provides a tool for text-to-speech synthesis.
tools/task
Package task provides a tool that lets the LLM spawn one-shot subagent runs for complex or parallelizable subtasks.
 Package task provides a tool that lets the LLM spawn one-shot subagent runs for complex or parallelizable subtasks.
tools/todo
Package todo provides LLM tools for managing a todo list.
 Package todo provides LLM tools for managing a todo list.
tools/transcribe
Package transcribe provides a tool for speech-to-text transcription.
 Package transcribe provides a tool for speech-to-text transcription.
tools/vision
Package vision provides a tool for LLM-based image analysis and text extraction.
 Package vision provides a tool for LLM-based image analysis and text extraction.
tools/webfetch
Package webfetch provides a tool for fetching web pages and converting them to markdown.
 Package webfetch provides a tool for fetching web pages and converting them to markdown.
tools/websearch
Package websearch provides a tool for searching the web via DuckDuckGo.
 Package websearch provides a tool for searching the web via DuckDuckGo.
tools/write
Package write provides full-file write operations.
 Package write provides full-file write operations.
ui
Package ui provides interfaces and event types for user interaction.
 Package ui provides interfaces and event types for user interaction.
ui/headless
Package headless provides a UI that prints events to stdout without user input.
 Package headless provides a UI that prints events to stdout without user input.
ui/simple
Package simple provides a readline-based TUI implementation.
 Package simple provides a readline-based TUI implementation.
ui/tui
Package tui implements a terminal user interface using bubbletea.
 Package tui implements a terminal user interface using bubbletea.
ui/tui/autocomplete
Package autocomplete provides directive name and path completions for the TUI.
 Package autocomplete provides directive name and path completions for the TUI.
ui/web
Package web provides a browser-based UI that streams HTML fragments over SSE.
 Package web provides a browser-based UI that streams HTML fragments over SSE.
pkg
auth
Package auth manages persistent token storage for OAuth-based providers.
 Package auth manages persistent token storage for OAuth-based providers.
auth/codex
Package codex implements the OpenAI device code flow for ChatGPT/Codex authentication.
 Package codex implements the OpenAI device code flow for ChatGPT/Codex authentication.
auth/copilot
Package copilot implements the GitHub device code flow for Copilot authentication.
 Package copilot implements the GitHub device code flow for Copilot authentication.
auth/devicecode
Package devicecode implements the shared device code polling loop for OAuth flows.
 Package devicecode implements the shared device code polling loop for OAuth flows.
clipboard
Package clipboard provides system clipboard access via OSC 52 terminal escape sequences.
 Package clipboard provides system clipboard access via OSC 52 terminal escape sequences.
frontmatter
Package frontmatter provides YAML frontmatter parsing from markdown files.
 Package frontmatter provides YAML frontmatter parsing from markdown files.
gitutil
Package gitutil provides git repository operations: cloning, pulling, commit tracking, origin metadata management, directory copying, and URL parsing.
 Package gitutil provides git repository operations: cloning, pulling, commit tracking, origin metadata management, directory copying, and URL parsing.
glob
Package glob provides filesystem globbing using doublestar patterns.
 Package glob provides filesystem globbing using doublestar patterns.
image
Package image provides image reading and compression with automatic resizing.
 Package image provides image reading and compression with automatic resizing.
llm/embedding
Package embedding defines common types for embedding operations.
 Package embedding defines common types for embedding operations.
llm/generation
Package generation defines optional sampling, output, and thinking budget parameters for LLM requests.
 Package generation defines optional sampling, output, and thinking budget parameters for LLM requests.
llm/message
Package message defines the Message type and Messages collection for LLM conversations, including filtering, compaction, export, and rendering.
 Package message defines the Message type and Messages collection for LLM conversations, including filtering, compaction, export, and rendering.
llm/model
Package model defines model metadata and collections.
 Package model defines model metadata and collections.
llm/part
Package part defines message part types for content, thinking, and tool calls.
 Package part defines message part types for content, thinking, and tool calls.
llm/request
Package request defines the common chat request structure.
 Package request defines the common chat request structure.
llm/rerank
Package rerank defines the common reranking request and response structures.
 Package rerank defines the common reranking request and response structures.
llm/responseformat
Package responseformat defines structured output constraints for LLM responses.
 Package responseformat defines structured output constraints for LLM responses.
llm/roles
Package roles defines conversation message roles.
 Package roles defines conversation message roles.
llm/stream
Package stream provides streaming output for chat completions.
 Package stream provides streaming output for chat completions.
llm/synthesize
Package synthesize defines common types for text-to-speech operations.
 Package synthesize defines common types for text-to-speech operations.
llm/thinking
Package thinking defines thinking levels, values, and management strategies for LLM reasoning.
 Package thinking defines thinking levels, values, and management strategies for LLM reasoning.
llm/tool
Package tool defines the tool interface and collection operations.
 Package tool defines the tool interface and collection operations.
llm/tool/call
Package call defines the tool call type used in LLM messages.
 Package call defines the tool call type used in LLM messages.
llm/transcribe
Package transcribe defines common types for speech-to-text operations.
 Package transcribe defines common types for speech-to-text operations.
llm/usage
Package usage defines token usage tracking.
 Package usage defines token usage tracking.
providers
Package providers defines the common interface for LLM provider implementations.
 Package providers defines the common interface for LLM provider implementations.
providers/adapter
Package adapter bridges Aura's LLM types with Fantasy's unified provider abstraction.
 Package adapter bridges Aura's LLM types with Fantasy's unified provider abstraction.
providers/anthropic
Package anthropic implements the Anthropic Messages API provider.
 Package anthropic implements the Anthropic Messages API provider.
providers/capabilities
Package capabilities defines model capability flags.
 Package capabilities defines model capability flags.
providers/codex
Package codex implements the OpenAI Plus (ChatGPT Codex) provider.
 Package codex implements the OpenAI Plus (ChatGPT Codex) provider.
providers/copilot
Package copilot implements the GitHub Copilot dual-protocol provider.
 Package copilot implements the GitHub Copilot dual-protocol provider.
providers/google
Package google implements the Google Gemini API provider.
 Package google implements the Google Gemini API provider.
providers/llamacpp
Package llamacpp implements the llama.cpp server provider.
 Package llamacpp implements the llama.cpp server provider.
providers/noop
Package noop provides a no-operation LLM provider that returns fixed responses without making any network calls.
 Package noop provides a no-operation LLM provider that returns fixed responses without making any network calls.
providers/ollama
Package ollama implements the Ollama provider.
 Package ollama implements the Ollama provider.
providers/openai
Package openai implements a generic OpenAI-compatible provider for any /v1/chat/completions endpoint.
 Package openai implements a generic OpenAI-compatible provider for any /v1/chat/completions endpoint.
providers/openrouter
Package openrouter implements the OpenRouter provider.
 Package openrouter implements the OpenRouter provider.
providers/registry
Package registry provides model capability enrichment using Catwalk metadata.
 Package registry provides model capability enrichment using Catwalk metadata.
providers/transport
Package transport provides HTTP transport with Bearer token authentication.
 Package transport provides HTTP transport with Bearer token authentication.
sandbox
Package sandbox provides Landlock LSM filesystem sandboxing for process isolation.
 Package sandbox provides Landlock LSM filesystem sandboxing for process isolation.
spinner
Package spinner provides a styled terminal spinner with optional no-op behavior.
 Package spinner provides a styled terminal spinner with optional no-op behavior.
tokens
Package tokens provides token count estimation and limit checks.
 Package tokens provides token count estimation and limit checks.
truncate
Package truncate provides text truncation and formatting utilities.
 Package truncate provides text truncation and formatting utilities.
truthy
Package truthy parses boolean-like string values (true/on/yes/enabled/1 and their inverses).
 Package truthy parses boolean-like string values (true/on/yes/enabled/1 and their inverses).
wildcard
Package wildcard provides simple wildcard pattern matching for tool filtering.
 Package wildcard provides simple wildcard pattern matching for tool filtering.
yamlutil
Package yamlutil provides strict YAML unmarshaling that rejects unknown fields.
 Package yamlutil provides strict YAML unmarshaling that rejects unknown fields.
sdk module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.