Command Line Interface

The ares-server binary is the single entry point. Run it without a subcommand to start the server, or use a subcommand to manage a project.

$ ares-server --help
A production-grade agentic chatbot server with multi-provider LLM support,
tool calling, RAG (Retrieval Augmented Generation), and MCP integration.

Run without arguments to start the server, or use 'init' to scaffold a new project.

Usage: ares-server [OPTIONS] [COMMAND]

Commands:
  init    Initialize a new A.R.E.S project with configuration files
  config  Show configuration information
  agent   Manage agents
  rag     Ingest and search RAG collections through the ARES API
  help    Print this message or the help of the given subcommand(s)

Global options

These options work on every command:

Global flag placement

Every option carries global = true (src/cli/mod.rs). Place a global flag before or after the subcommand. These two lines parse identically:

ares-server --no-color config --validate
ares-server config --validate --no-color

-v, --verbose changes the log filter of a server run from info to debug,ares=trace (run_server, src/main.rs). Subcommands print their diagnostics to standard error regardless of this flag.

--mcp needs the mcp build feature. Without it, the binary prints a rebuild hint and exits 1.

Supervisor semantics

--supervise runs the real server in a child copy of the same executable. The child signals the parent through its exit code:

The constants live in src/supervisor.rs. The child carries the CORDIS_SUPERVISED environment variable. The daemon holds the write end of the child's standard input. Dropping it closes the pipe, so the child sees end-of-file and tears down gracefully.

Example: run a daemon that survives hot restarts:

ares-server --supervise

Pair it with a service manager such as systemd. Boot failures still surface as non-zero exits.

Restart safeguards

Four safeguards keep the loop responsive (src/supervisor.rs):

• Rapid-restart guard. Five exits inside any 30-second window stop the loop. This bounds a crash loop that a misbehaving child cannot out-wait.
• Health ladder reset. A child that ran for at least 10 minutes before exiting counts as healthy. The next crash sequence starts its backoff from zero, not from stale strikes.
• Exponential backoff. A child that exited within 10 seconds never proved it could serve. The daemon delays the respawn: 100 ms first, then double each consecutive unhealthy run, capped at 5 s.
• Stop grace. A stopped worker gets 10 seconds to exit after its standard input closes. A worker that ignores the request is force-killed.

Exit codes

Use these codes in scripts and service units:

Two details matter for wrappers:

• Without --supervise, a failing boot returns 1. With --supervise, the parent mirrors the real child code (exit(last_code & 0xff)), so a boot failure surfaces as 53.

init

Scaffold a new project. Creates ares.toml, a .env.example template, the data/ directory, and the config/ directory tree with example TOON files.

$ ares-server init [OPTIONS] [PATH]

Example session:

$ ares-server init --minimal
   Agentic Runtime Extensible Server v0.10.0

  Initializing A.R.E.S Project

  Creating directories
  ✓ directory data
  ✓ directory config/agents
  ✓ directory config/models

  Creating configuration files
  ✓ config ares.toml
  ✓ env .env.example

  A.R.E.S project initialized successfully!

config

Show configuration information.

$ ares-server config [OPTIONS]

Example summary:

$ ares-server config
  Configuration Summary

    Config file: ares.toml
    Server: 127.0.0.1:3000
    Log level: info

  Providers
    • ollama-local

  Agents
    • orchestrator
    • router

Validation fails when a referenced environment variable is missing, or when an agent references an unknown provider. A zero exit code means the file is valid:

$ ares-server config --validate
  ✓ Configuration is valid!

agent

Manage configured agents.

$ ares-server agent <COMMAND>

Subcommands:

• list — list all configured agents.
• show <NAME> — show details for one agent.

Example listing:

$ ares-server agent list
  Configured Agents

    Name            Model                        Tools
    ────────────────────────────────────────────────
    router          meta/llama-3.3-70b-instruct  -
    orchestrator    meta/llama-3.3-70b-instruct  calculator, web_search

Show one agent by name:

ares-server agent show orchestrator

Both commands read the same sources as the server: static agents from ares.toml plus TOON files in the configured directories.

rag

Ingest documents into RAG collections and search them. These commands are API clients: they call a running ARES server over HTTP, so start the server first.

Authenticate with --user and --password, or skip login with --token. Both forms accept --host for a remote server. Default host: http://localhost:3000.

rag ingest-dir

Recursively ingest local text documents into a collection.

$ ares-server rag ingest-dir [OPTIONS] --collection <COLLECTION> --docs-path <DOCS_PATH>

All options (--help output):

Preview an ingest before running it:

ares-server rag ingest-dir \
  --collection docs \
  --docs-path ./handbook \
  --tag handbook \
  --dry-run

Remove --dry-run to perform the ingest.

rag search

Search a collection.

$ ares-server rag search [OPTIONS] --collection <COLLECTION> --query <QUERY>

All options (--help output):

Example:

ares-server rag search \
  --collection docs \
  --query "how do I rotate API keys" \
  --top-k 5 \
  --strategy hybrid

Scripting and composition

Every command reports its result through the exit code. Chain commands with && so a later step runs only after an earlier step succeeds.

Validate, then start under the supervisor:

ares-server config --validate && ares-server --supervise

Preview an ingest, then run it for real:

ares-server rag ingest-dir --collection docs --docs-path ./handbook --dry-run \
  && ares-server rag ingest-dir --collection docs --docs-path ./handbook \
       --tag handbook --user me@example.com --password "$PASS"

Scripting guidance:

• Check $? after each call. 0 means success; see the exit-code table above for failure codes.
• --verbose raises server log verbosity to debug,ares=trace. It does not change subcommand output.
• Progress lines go to standard output; failures go to standard error. Redirect them separately: 2>err.log.
• A failed ingest still processes every document first. The summary line on stdout reads summary<TAB>documents=N succeeded=S failed=F chunks=C; parse it to decide whether to retry.
• A dry run prints one tab-separated line per file: <path><TAB><title><TAB><N bytes>, then dry_run=true documents=<count>. Both formats are stable for parsing.

A guarded ingest in shell:

if ares-server rag ingest-dir --collection docs --docs-path ./handbook \
     --token "$ARES_TOKEN" > out.log 2> err.log; then
  grep '^summary' out.log
else
  cat err.log
  exit 1
fi

Where to go next

• Scaffold and run your first project: First Server.
• Call the server over HTTP instead of the CLI: HTTP API.