Octavo in your terminal
Octavo Team · 4 min read

The Octavo CLI runs on macOS, Linux and Windows, with the same agent as the Octavo editor. The agent reads your code, plans the work, edits across files, runs commands and tests, and shows you a diff of every change.
What changes is where it runs. The CLI needs only a shell, so it works on your laptop, on a remote server over SSH, inside a container and in a CI job. This post covers working with it in a session, running it from scripts and CI, and taking it to servers and containers.
Get the CLI
Your organization rolls out the Octavo CLI together with the editor. Once it is on your machine, open a terminal in a repository and run octavo. The rollout page explains how a company deploys it.
Work in a session
octavo starts an interactive session in the current directory. The welcome banner shows Otto, our octopus mascot, next to the current model and the working directory. Type /help to list the commands.
From there you work the way you would in the editor. Ask a question, such as why the nightly reconcile job is slow, and the agent reads the relevant files before it answers. Ask for a change and it can write a plan first, with the steps it intends to take. Reply to adjust the plan, or tell it to go.
Once you approve, the agent edits the files, runs your tests, reads any failures and fixes them. Each edit appears in the terminal as a diff, so you know what changed before you commit. You can type a follow-up at any point to steer the work.
The CLI uses the same models as the editor. Auto picks a model for each request, or you can choose one yourself.
Run it headless
octavo -p runs a single task without a session and exits when the task is done. Pass the task as a quoted prompt. The result goes to standard output as plain text, or as JSON for scripts that need to parse it:
octavo -p \ "List the exported functions in src/billing that no test calls" \ --output-format jsonHeadless mode is how the CLI fits into scripts, git hooks and scheduled jobs. The agent writes its findings or its changes, and your pipeline decides where they go and who reviews them.
Use it in CI
A useful first job is explaining test failures. The workflow below runs the test suite on every pull request. When the tests fail, the agent reads the output and the code it points to, and writes a short explanation to the job summary.
name: testson: pull_request jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: npm ci - name: Run tests shell: bash run: npm test 2>&1 | tee test-output.txt - name: Explain the failure if: failure() env: OCTAVO_API_KEY: ${{ secrets.OCTAVO_API_KEY }} PROMPT: >- The tests failed. Read test-output.txt and the code it points to. Explain the cause in under 100 words and name the file to fix. run: | ./ci/install-octavo.sh octavo -p "$PROMPT" >> "$GITHUB_STEP_SUMMARY"ci/install-octavo.sh installs the CLI build your organization approved, and the job authenticates with an API key an admin creates for CI.
The engineer who opened the pull request reads the explanation next to the failed check. The same pattern works for other jobs: summarize a dependency upgrade, check a migration against the current schema, or draft release notes from merged pull requests. Each job is one command with a prompt, and its output goes wherever your pipeline sends it.
Over SSH and in containers
The CLI runs where the code lives. Connect over SSH to a build server or remote workstation where your organization has installed the CLI, and run octavo. The agent works with that machine’s files and toolchain, and nothing has to sync to your laptop first.
Containers work the same way. Add the CLI build your organization approved to your development image, then start a session inside the running container:
docker exec -it ledger-api-dev octavoThe agent’s commands and tests now run against the container’s dependencies. When CI builds from the same image, a test that passes in the session passes for the same reasons in CI.
Send a task to the cloud
Tasks you don’t need to watch can run in Octavo Cloud while you keep working in the terminal. octavo cloud starts a cloud agent with a prompt:
octavo cloud "Move the invoice PDF renderer to the shared worker queue"Each cloud agent runs in its own VM with your repository, dependencies and tools. It returns a branch and a pull request with a summary and test results. You review it like any other pull request.
Get started
Once your organization has rolled out the CLI, run octavo in a repository you know well. Ask it something you already know the answer to, then give it a small change and read the diff. The documentation covers the CLI in detail, and the features page shows how it fits with the editor and cloud agents.


