HomeAgents CLI
Overview
This is a small PowerShell runner for the HomeAgents platform. The platform has several repositories, and I got tired of remembering the compose file names, the env file flags and the folders for each one.
Now I type one command, like homeagents chat run, and the CLI does the rest. There are seven stages and four actions, and the shape never changes.
I kept it thin on purpose. It only starts and stops stacks. The two exceptions to the pattern are written down in the README, so I do not have to remember them either.
Problem
My AI platform is split into several repositories, and each one has its own compose file, its own env file flags and its own working directory. I did not want to remember all of that every time I start or stop something. I wanted one command that always looks the same.
Approach
- I wrote a thin PowerShell runner and kept it deliberately small.
- I gave every command the same shape: the stage first, then the action. For example, homeagents chat run.
- I made seven stages that cover the whole platform: core, websearch, programming, finance, chat, dify and document-ingestion.
- I gave every stage the same four actions where they make sense: run, stop, restart and status.
- I let the CLI start and stop the stacks only. It calls no model itself.
Architecture and design decisions
- A main script called homeagents.ps1 maps the stage and the action to the script of that stage.
- Each stage has its own folder with its run and stop scripts, so the behaviour stays predictable.
- A logging helper gives every script the same style of output for steps, info and warnings.
- A paths helper finds every repository from one root folder. It checks the ReposRoot parameter first, then the HOMEAGENTS_REPOS_ROOT environment variable, then the parent folder of the CLI repository.
- Because of that, the repository contains no absolute paths, and the same clone works on any machine.
- The run action first makes sure the shared ai-platform-net Docker network exists. It does this safely, so running it twice does no harm.
Reliability and performance
- Creating the shared network is idempotent, so a repeated run never fails because the network is already there.
- The document-ingestion stage only has a run script, because it is a one shot job and there is nothing to stop.
- The Dify stage does not pass an env file, because Dify keeps its own .env next to its compose file.
- Restart is only implemented for the programming stage, because OpenHands needs its workspace path set again before the container starts.
- I wrote these exceptions down in the README and did not hide them in the code.
Outcomes
- Seven stages of the platform start and stop with one command shape.
- I no longer type long compose commands or remember file names and flags.
- The repository has no absolute paths, so it works on another machine without edits.
- The special cases are documented, so nothing surprises me later.
Known gaps
- It is a thin wrapper around Docker Compose. It does not add health checks or any logic beyond starting and stopping.
- I have not tested it on Linux or macOS. It needs PowerShell and Docker Compose v2.
- Restart does not work for every stage.
- I do not say which licence the repository uses.
- I have no numbers on how much time it saves.