Standalone CLI

The standalone CLI mode runs Open Astra as an interactive REPL agent in your terminal. It is the simplest way to use Astra for personal automation — it only requires one inference API key and a PostgreSQL database.

ℹThe standalone CLI does not start the HTTP gateway or WebSocket server. If you need the REST API or messaging channel integrations, use Docker Compose or npx astra instead.

Setup

bash

# Install globally for convenient access
npm install -g @open-astra/astra

# Or run directly without installing
npx astra chat

Standalone .env configuration

Create a .env.standalone file (or a standard .env) with only the minimum required variables:

bash

# Minimum required for standalone CLI
OPENAI_API_KEY=sk-...        # or any other provider key

# PostgreSQL — required for memory persistence
PG_HOST=localhost
PG_PORT=5432
PG_DATABASE=astra
PG_USER=astra
PG_PASSWORD=astra

# Typesense — optional but recommended for memory search
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
TYPESENSE_API_KEY=change-me

If Typesense is not configured, memory search falls back to PostgreSQL full-text search only.

CLI commands

Once started, the CLI accepts natural language input as well as slash commands:

Command	Description
`/help`	Show all available commands
`/agent <id>`	Switch to a different agent by ID
`/agents`	List all configured agents
`/reset`	Clear the current session conversation history
`/memory <query>`	Search memory for a query and display results
`/usage`	Show token and cost usage for this session
`/exit` or `Ctrl+C`	Exit the CLI

Agent selection

On startup, the CLI connects to the default agent defined in your astra.yml. You can switch agents at any time during the session:

bash

# Start CLI
npx astra chat

# Inside the REPL:
> /agents
  1. default-agent  (gpt-4o)
  2. research-agent (claude-opus-4-6)
  3. code-agent     (gpt-4o)

> /agent research-agent
Switched to research-agent

> Tell me about the latest advances in pgvector indexing...

Running with npm scripts

If you have cloned the repository, you can use the npm scripts directly:

bash

# Interactive REPL with auto-restart on file changes (development)
npm run cli:dev

# Interactive REPL (production mode, no restart)
npm run cli

# One-shot — run a single prompt and exit
npm run cli -- --prompt "Summarize today's git commits"

Output formats

The CLI supports two output modes:

Interactive (default) — streams response tokens as they arrive, renders markdown
JSON — pass --json flag to get structured output for piping to other tools

bash

# Get JSON output for scripting
npx astra chat --json --prompt "List all open issues" | jq '.content'