Documentation
Everything you need to install Sage, sign in, pull models, and drive a session from the command line — including the slash commands, shell escapes, and the SMS bridge.
Install
Sage ships as a Python package. If you have Python and pip, you have everything you need:
•
pip install sage-ai-cli — installs the sage command onto your PATH.
•
sage — starts an interactive session in the current directory. Sage treats the directory you launch it from as the project it is working on.
•
sage --version — confirms which build you are running. Include this whenever you report a problem.
If the sage command is not found after installing, your Python scripts directory is not on your PATH. Running it as a module — python -m sage — works as a fallback while you sort that out.
Sign in
Run sage login. The CLI opens your browser, you authenticate with Google or Apple, and the resulting token is written to a configuration file in your home directory. You stay signed in across sessions and reboots until you run sage logout.
Signing in links the CLI to your plan so cloud models and your output token allowance become available. Local models run whether you are signed in or not — that is the point of local-first.
Getting models
Sage works with over 200 open-weight models: Llama, Gemma, Qwen, Mistral, Phi, DeepSeek-Coder, Devstral, and more. You can run them as local GGUF weights on your own hardware or route to a cloud-hosted copy.
•
sage pull <model> — downloads a model's weights to your machine for local, fully offline use. Larger models need more RAM or VRAM; start small if you are unsure what your machine can hold.
•
sage update — updates the CLI itself to the latest release. Run it when a command behaves unexpectedly or before filing a bug.
•
/models — lists what is available to you, local and cloud, from inside a session.
•
/model <name> — switches the active model mid-conversation without losing your context.
Local models cost you nothing but disk and compute. Cloud models draw down the output token allowance on your plan, and requests are anonymized before they leave your machine — identifiers stripped, emails and phone numbers scrubbed.
Slash commands
Inside a session, anything starting with a slash is handled by Sage rather than sent to the model:
•
/help — lists every command available in your build. The authoritative reference, since it reflects the version you actually have.
•
/models — shows the models you can use right now, local and cloud.
•
/model <name> — switch the active model without restarting or losing the conversation.
•
/think — turn on extended reasoning. The model works through the problem more deliberately before answering. Slower, and it generates more output tokens, so use it for genuinely hard problems rather than routine edits.
•
/test — run your project's test suite and feed the results back to Sage, so it can iterate against real failures instead of guessing.
•
/read <path> — pull a specific file into context. Use it when Sage is reasoning about the wrong version of something.
•
/files — show which files are currently in context. Worth checking when answers seem to be missing obvious information.
•
/compact — summarize the conversation so far and discard the raw history. This is how you keep a long session inside the context window without starting over.
•
/undo — reverse Sage's most recent file changes. It is a safety net for a bad edit, not a replacement for version control.
•
/status — show your plan, output token usage for the period, and the active model.
•
/clear — wipe the conversation and start fresh in the same directory.
•
/exit — end the session.
Running shell commands
Prefix any line with an exclamation mark to run it in your shell without leaving Sage. !git status, !npm test, !ls -la — the command runs in your project directory and the output comes back into the session, so Sage can see it and reason about it. This is the fastest way to give Sage ground truth about the state of your repository.
Multi-line input
Pressing Enter sends your message, which is awkward when you want to paste a stack trace or write a long specification. Open with three double quotes ("""), type or paste as many lines as you need, then close with three double quotes on their own line. Everything between them is sent as a single prompt with its formatting intact.
Working effectively
•
Launch Sage from the root of the project you are working on — that directory is the scope it reasons about.
•
Commit before a large refactor. /undo covers the last change; git covers everything else.
•
Use /compact when replies start losing the thread. A long session eventually crowds out the early context.
•
Use /test rather than describing failures by hand. Real output beats a paraphrase every time.
•
Reach for /think when a problem is genuinely hard, not by default — it costs more output tokens.
•
Check /status before a long session so you know how much of your allowance is left.
Editor and tool integrations
Sage integrates with the tools you already use, so you do not have to change how you work:
•
Editors and IDEs — VS Code, Cursor, JetBrains, Neovim, Sublime Text, and Zed.
•
Version control — GitHub CLI and Git Hooks, so Sage can participate in your commit and review flow.
•
Game engines — Godot 4 and the Unity Editor.
The SMS bridge
The SMS bridge lets you send a task to one of your own computers from your phone — through iMessage, Google Messages, or email — and have Sage carry it out there. The machine does the work with its own models and its own copy of your code; your phone is only the remote control.
•
Register the machine you want to reach from the Devices page in the Sage web app, and give it a name you will recognize in a text message.
•
Keep that machine running with Sage available. If the computer is asleep, there is nothing listening.
•
Add the phone numbers and email addresses allowed to send it tasks. Only allowlisted senders are accepted — everything else is ignored.
•
Send a message naming the device and the task, and the reply comes back over the same channel.
•
Remove a device or a sender from the Devices page the moment you no longer control it. A lost phone is a lost credential.
Treat the allowlist as seriously as an SSH key. Anything an allowlisted sender asks for can run on that machine.
Privacy while you work
By default Sage runs on your machine: prompts, source code, and files are processed locally and never transmitted. Only when you explicitly select a cloud model does a request leave, and it is anonymized first. Your code is never used to train models.
Getting help
Run /help first — it reflects the exact build you have installed, which this page cannot. If something is still wrong, email support@sageworksai.com with the output of sage --version, the command you ran, and what happened instead of what you expected.