acra-cli 0.1.1

Agentic CLI for LLM task execution, research, and workflow automation.

acra

Agentic CLI for LLM-powered research, task execution, code generation, workflow automation, memory, and sandboxed validation.

acra is an installable Python package that provides the acra command-line tool and a reusable LangGraph-based agent workflow. It is built for developers who want a local CLI for asking an LLM-powered agent to research, plan, generate code, validate generated projects, and keep workflow context across runs.

Status: beta. The package is usable, but some CLI command groups are still scaffolds. The most complete surfaces today are installation, provider configuration, profile setup, key management, the interactive shell, research workflows, and Python-level workflow APIs.

Highlights

• Installable Python package with a console script: acra
• Interactive CLI shell powered by Typer, Rich, and prompt-toolkit
• LangGraph workflow with planner, researcher, coder, executor, critic, memory, and human nodes
• Provider support for Gemini, OpenAI, Groq, Ollama, and HuggingFace
• Configuration profiles stored in ~/.acra/config.json
• OS keyring support for API keys
• Research command with depth, sources, formatting, output, JSON, and memory options
• Generated project saving and validation
• ChromaDB-backed vector memory and JSON workflow memory modules
• Optional extras for provider-specific dependencies and checkpoint backends

Requirements

• Python >=3.11
• At least one supported LLM provider or local inference backend
• Optional: Docker, if you use execution paths that run generated projects in containers

Installation

Install the base package:

pip install acra

Install provider-specific extras as needed:

pip install "acra[openai]"
pip install "acra[groq]"
pip install "acra[ollama]"
pip install "acra[huggingface]"

Install checkpointing extras:

pip install "acra[sqlite]"
pip install "acra[postgres]"

Install multiple extras together:

pip install "acra[openai,groq,sqlite]"

After installation, run:

acra

or:

python -m acra

Quick Start

Configure a provider:

export LLM_PROVIDER=gemini
export GOOGLE_GEMINI_API_KEY="your-key"

Start the interactive shell:

acra

Create a local configuration profile:

acra config init

Show the active profile:

acra config show

Store a key in your OS keyring:

acra keys set provider

Run a research workflow:

acra research research "Compare LangGraph and CrewAI for code-generation workflows"

The repeated research research is intentional in the current CLI: the first research is the command group and the second research is the subcommand.

Provider Configuration

acra reads provider settings from environment variables. Select the active backend with:

export LLM_PROVIDER=gemini

Supported values:

• gemini
• openai
• groq
• ollama
• huggingface_local
• huggingface_cloud

Common optional setting:

export LLM_TEMPERATURE=0.6

Gemini

Gemini support is included in the base package dependencies.

export LLM_PROVIDER=gemini
export GEMINI_MODEL=gemini-2.5-flash
export GOOGLE_GEMINI_API_KEY="your-key"

GEMINI_API_KEY is also accepted as a fallback credential variable.

OpenAI

pip install "acra[openai]"

export LLM_PROVIDER=openai
export OPENAI_MODEL=gpt-4o-mini
export OPENAI_API_KEY="your-key"

Groq

pip install "acra[groq]"

export LLM_PROVIDER=groq
export GROQ_MODEL=llama-3.3-70b-versatile
export GROQ_API_KEY="your-key"

Ollama

pip install "acra[ollama]"

export LLM_PROVIDER=ollama
export OLLAMA_MODEL=mistral
export OLLAMA_BASE_URL=http://localhost:11434

Make sure Ollama is running:

ollama serve

HuggingFace Cloud

pip install "acra[huggingface]"

export LLM_PROVIDER=huggingface_cloud
export HF_MODEL=mistralai/Mistral-7B-Instruct-v0.1
export HF_API_KEY="your-token"

HuggingFace Local

pip install "acra[huggingface]"

export LLM_PROVIDER=huggingface_local
export HF_MODEL=mistralai/Mistral-7B-Instruct-v0.1
export HF_DEVICE=cpu

Use HF_DEVICE=cuda for compatible GPU environments.

Configuration Profiles

Profiles are stored in:

~/.acra/config.json

Create or update the default profile:

acra config init

Create a named profile:

acra config init --profile work

Show a profile:

acra config show
acra config show --profile work

The setup wizard prompts for:

• provider
• model
• provider API key
• theme
• workspace path
• research API keys

Key Management

acra can store credentials in your operating system keyring.

Set a key interactively:

acra keys set provider

Set a key directly:

acra keys set provider "your-key"

List key status:

acra keys list

Delete a key:

acra keys delete provider

Research key names:

acra keys set research.web
acra keys set research.github
acra keys set research.docs
acra keys set research.arxiv

Environment fallback variables:

• ACRA_PROVIDER_KEY
• ACRA_RESEARCH_WEB_KEY
• ACRA_RESEARCH_GITHUB_KEY
• ACRA_RESEARCH_DOCS_KEY
• ACRA_RESEARCH_ARXIV_KEY

CLI Usage

Run the top-level help after installation:

acra --help

Global options include:

• --profile
• --workspace
• --no-memory
• --dry-run
• --json
• --verbose / -v
• --quiet / -q
• --timeout

Interactive Shell

Running acra without a subcommand starts the shell:

acra

You can also launch it explicitly:

acra serve

Inside the shell, type commands such as:

config show
keys list
research research "What are good approaches for agent memory?"
memory list
session list
graph show
exit

Research

Run:

acra research research "What is the best architecture for a local-first AI coding agent?"

Options:

• --depth: shallow, standard, or deep
• --sources: comma-separated source list
• --format: citations, summary, or detailed
• --output: write output to a file
• --save: persist research output into memory
• --follow-up: keep the session open for follow-up questions
• --no-memory: skip memory persistence
• --profile: select a profile
• --json: output JSON
• --verbose / -v: show detailed output

Examples:

acra research research "Survey Python sandboxing options" --depth deep

acra research research "Compare ChromaDB and FAISS for agent memory" \
  --sources web,github,arxiv \
  --format detailed \
  --output research-report.md

acra research research "LangGraph checkpointing options" \
  --format summary \
  --json

Other Commands

Configuration:

acra config init
acra config show

Keys:

acra keys set provider
acra keys list
acra keys delete provider

Memory:

acra memory list
acra memory search "previous docker error"
acra memory clear

Sessions:

acra session list
acra session resume <session-id>

Graph:

acra graph show
acra graph run

Note: memory, session, and graph command groups are currently available but include placeholder handlers in this beta release. The underlying Python modules are more complete than the current CLI wrappers.

Python Usage

The package exposes reusable workflow and configuration modules.

Run the compiled LangGraph workflow:

from acra.graph.workflow import OmniAgentCallbacks, create_workflow

workflow = create_workflow()

result = workflow.invoke(
    {
        "user_request": "Build a small Python CLI that validates JSON files",
        "interactive": False,
        "retry_count": 0,
        "max_retries": 5,
    },
    config={"callbacks": [OmniAgentCallbacks()]},
)

print(result)

Use the LLM factory:

from acra.agents.llm import llm

model = llm()
response = model.invoke("Say hello in one sentence.")

print(response.content if hasattr(response, "content") else response)

Load a profile:

from acra.config.profile_manager import ProfileManager

profile = ProfileManager().load_profile()
print(profile)

Use JSON memory:

from acra.agents.memory.memory_manager import get_memory_manager

memory = get_memory_manager("example-session")
memory.add_memory(
    "workflow_result",
    {
        "user_request": "Create a CLI",
        "execution_success": True,
        "quality_score": 8.5,
    },
)

print(memory.get_recent_memories(limit=3))

Data Locations

Profile configuration:

~/.acra/config.json

Application data is stored in a platform-specific user data directory resolved with platformdirs.

Override it with:

export OMNIAGENT_DATA_DIR=/path/to/acra-data

Important subdirectories:

• projects/: generated project files
• memory/storage/: JSON memory files
• memory/chroma_db/: ChromaDB vector memory
• memory/checkpoints/data/: workflow checkpoint data

Current Beta Notes

• The package version is 0.1.0.
• The top-level CLI currently attaches serve, config, keys, research, memory, session, graph, and workspace.
• The codebase contains additional command modules such as brain, context, logs, and plugin, but they are not currently attached to the top-level CLI.
• Some CLI command groups return placeholder output while the Python modules behind them continue to evolve.

Troubleshooting

Missing provider dependency

Install the matching extra:

pip install "acra[openai]"
pip install "acra[groq]"
pip install "acra[ollama]"
pip install "acra[huggingface]"

Missing API key

Set the provider key:

export GOOGLE_GEMINI_API_KEY="your-key"
export OPENAI_API_KEY="your-key"
export GROQ_API_KEY="your-key"
export HF_API_KEY="your-token"

Or store it with:

acra keys set provider

Ollama connection failure

Start Ollama and make sure the model is available:

ollama serve
ollama pull mistral

Then configure:

export LLM_PROVIDER=ollama
export OLLAMA_MODEL=mistral
export OLLAMA_BASE_URL=http://localhost:11434

License

acra is licensed under the GNU Affero General Public License v3.

Package Metadata

• Package name: acra
• Version: 0.1.0
• Python: >=3.11
• Console script: acra=acra.cli:app_main
• Author: Raj Tembe