sagex-cli 1.0.0__tar.gz → 2.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. {sagex_cli-1.0.0/sagex_cli.egg-info → sagex_cli-2.0.0}/PKG-INFO +61 -21
  2. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/README.md +58 -19
  3. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/pyproject.toml +2 -1
  4. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/__init__.py +1 -1
  5. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/__main__.py +497 -47
  6. sagex_cli-2.0.0/sagex/api/auth.py +89 -0
  7. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/api/client.py +35 -7
  8. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/api/resources.py +93 -0
  9. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/api/store.py +17 -5
  10. sagex_cli-2.0.0/sagex/app.py +1030 -0
  11. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/app.tcss +8 -2
  12. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/config.py +53 -2
  13. sagex_cli-2.0.0/sagex/device.py +47 -0
  14. sagex_cli-2.0.0/sagex/local_tools.py +435 -0
  15. sagex_cli-2.0.0/sagex/models.py +69 -0
  16. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/pusher.py +38 -18
  17. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/render.py +49 -0
  18. sagex_cli-2.0.0/sagex/sage.py +246 -0
  19. sagex_cli-2.0.0/sagex/sage_text.py +252 -0
  20. sagex_cli-2.0.0/sagex/sage_tools.py +517 -0
  21. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/shell.py +8 -4
  22. sagex_cli-2.0.0/sagex/usage.py +147 -0
  23. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/widgets/message.py +27 -6
  24. sagex_cli-2.0.0/sagex/widgets/tool_card.py +278 -0
  25. {sagex_cli-1.0.0 → sagex_cli-2.0.0/sagex_cli.egg-info}/PKG-INFO +61 -21
  26. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex_cli.egg-info/SOURCES.txt +18 -1
  27. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex_cli.egg-info/requires.txt +1 -0
  28. sagex_cli-2.0.0/tests/test_cli.py +284 -0
  29. sagex_cli-2.0.0/tests/test_local_tools.py +240 -0
  30. sagex_cli-2.0.0/tests/test_models.py +205 -0
  31. sagex_cli-2.0.0/tests/test_pusher.py +90 -0
  32. sagex_cli-2.0.0/tests/test_sage.py +284 -0
  33. sagex_cli-2.0.0/tests/test_sage_text.py +135 -0
  34. sagex_cli-2.0.0/tests/test_sage_tools.py +227 -0
  35. sagex_cli-2.0.0/tests/test_tool_card.py +45 -0
  36. sagex_cli-2.0.0/tests/test_tui.py +792 -0
  37. sagex_cli-2.0.0/tests/test_usage.py +74 -0
  38. sagex_cli-1.0.0/sagex/app.py +0 -378
  39. sagex_cli-1.0.0/tests/test_cli.py +0 -123
  40. sagex_cli-1.0.0/tests/test_tui.py +0 -26
  41. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/LICENSE +0 -0
  42. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/_env.py +0 -0
  43. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/api/__init__.py +0 -0
  44. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/copier.py +0 -0
  45. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/formatting.py +0 -0
  46. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/runner.py +0 -0
  47. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/runview.py +0 -0
  48. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/widgets/__init__.py +0 -0
  49. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/widgets/activity.py +0 -0
  50. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/widgets/prompt_input.py +0 -0
  51. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex/widgets/run_graph.py +0 -0
  52. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex_cli.egg-info/dependency_links.txt +0 -0
  53. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex_cli.egg-info/entry_points.txt +0 -0
  54. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/sagex_cli.egg-info/top_level.txt +0 -0
  55. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/setup.cfg +0 -0
  56. {sagex_cli-1.0.0 → sagex_cli-2.0.0}/setup.py +0 -0
@@ -1,10 +1,10 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: sagex-cli
3
- Version: 1.0.0
3
+ Version: 2.0.0
4
4
  Summary: Autosage in your terminal: build, run and watch workflows, scripts, vaults and triggers from a TUI or one-shot commands.
5
5
  Author: Lagnajit Moharana
6
6
  License-Expression: MIT
7
- Project-URL: Homepage, https://github.com/Lagnajit09/sagex
7
+ Project-URL: Homepage, https://sagecode.web.app
8
8
  Project-URL: Documentation, https://autosagexdocs.web.app
9
9
  Project-URL: Repository, https://github.com/Lagnajit09/sagex
10
10
  Project-URL: Issues, https://github.com/Lagnajit09/sagex/issues
@@ -31,6 +31,7 @@ Requires-Dist: httpx<0.29,>=0.28.1
31
31
  Requires-Dist: keyring<26,>=25.7.0
32
32
  Requires-Dist: typer<0.28,>=0.27.2
33
33
  Requires-Dist: cron-descriptor<3,>=2.1.0
34
+ Requires-Dist: websockets<17,>=14
34
35
  Provides-Extra: dev
35
36
  Requires-Dist: textual-dev==1.8.0; extra == "dev"
36
37
  Requires-Dist: pytest>=8; extra == "dev"
@@ -38,7 +39,7 @@ Dynamic: license-file
38
39
 
39
40
  # sagex
40
41
 
41
- **Autosage in your terminal.** Build, run and watch your [Autosage](https://autosagex.web.app) workflows, scripts, vaults and triggers from a full-screen terminal app or one-shot commands. Everything the web app does, minus the mouse.
42
+ **Autosage in your terminal.** Build, run and watch your [Autosage](https://autosagex.web.app) workflows, scripts, vaults and triggers from a full-screen terminal app or one-shot commands. Everything the web app does, minus the mouse, plus **Sage**: an assistant that looks things up, writes and pushes scripts, runs workflows and fixes what failed, asking you before it changes anything.
42
43
 
43
44
  [![PyPI](https://img.shields.io/pypi/v/sagex-cli)](https://pypi.org/project/sagex-cli/)
44
45
  [![Python](https://img.shields.io/pypi/pyversions/sagex-cli)](https://pypi.org/project/sagex-cli/)
@@ -54,7 +55,7 @@ $ sagex list workflow
54
55
  └──────────────────────┴──────────────────────────────────────┴──────────┘
55
56
  ```
56
57
 
57
- > **Early access.** sagex is invite-only for now. Your account needs an API key: [request one here](https://autosagex.web.app/contact).
58
+ You need an [Autosage account](https://autosagex.web.app/signup) (free).
58
59
 
59
60
  ## Install
60
61
 
@@ -70,7 +71,7 @@ curl -LsSf https://raw.githubusercontent.com/Lagnajit09/sagex/main/scripts/insta
70
71
  irm https://raw.githubusercontent.com/Lagnajit09/sagex/main/scripts/install.ps1 | iex
71
72
  ```
72
73
 
73
- The installer uses [uv](https://docs.astral.sh/uv/) to install sagex as an isolated tool, and fetches Python 3.11+ for you if needed. Set `SAGEX_VERSION=1.0.0` before running it to pin a version.
74
+ The installer uses [uv](https://docs.astral.sh/uv/) to install sagex as an isolated tool, and fetches Python 3.11+ for you if needed. Set `SAGEX_VERSION=2.0.0` before running it to pin a version.
74
75
 
75
76
  **Already have a Python tool manager?** Any of these works (Python 3.11 or newer):
76
77
 
@@ -83,8 +84,8 @@ pip install sagex-cli
83
84
  ## Quick start
84
85
 
85
86
  ```sh
86
- sagex auth login # paste your API key (stored in your OS keychain)
87
- sagex # open the terminal app
87
+ sagex auth login # approve this device in your browser
88
+ sagex # open the terminal app, then just ask Sage
88
89
  sagex list workflow # or run single commands
89
90
  sagex run workflow "Deploy" # run a workflow and follow it live, node by node
90
91
  ```
@@ -94,19 +95,44 @@ sagex run workflow "Deploy" # run a workflow and follow it live, node by node
94
95
  Run `sagex` with no arguments to open it.
95
96
 
96
97
  - **Left:** your **Resources**: Workflows, Scripts, Vault, recent Runs (with ✓ / ✗ / ⟳ status) and Triggers (● on / ○ off). Press **F3** to switch to your local **Workspace** folder instead.
97
- - **Right:** a terminal-style transcript. Start a line with `!` to run any command, such as `!sagex run workflow Deploy` or `!git status`. Output streams in live, and workflow runs draw a live node graph.
98
+ - **Right:** a terminal-style transcript. Start a line with `!` to run any command, such as `!sagex run workflow Deploy` or `!git status`. Output streams in live, and workflow runs draw a live node graph. Anything else goes to **Sage**.
99
+ - **Bottom left:** **Sage Today**: today's requests and tokens, the model Sage uses, and the free requests left.
98
100
 
99
101
  | Key | Action |
100
102
  |---|---|
101
103
  | `!command` | Run a shell or sagex command |
102
- | `Esc` | Stop the running command |
104
+ | *anything else* | Ask Sage |
105
+ | `Esc` | Stop the running command or Sage's reply |
103
106
  | `↑` / `↓` | Command history |
104
107
  | `F2` | Switch shell (PowerShell / cmd / WSL on Windows, bash / sh elsewhere) |
105
108
  | `F3` | Switch between server resources and the local workspace |
106
109
  | `F5` | Refresh |
107
110
  | `Ctrl+Q` | Quit |
108
111
 
109
- Chatting with Autobot from the terminal is coming in **sagex v2**. Until then, use Autobot in the [web app](https://autosagex.web.app/ai/autobot).
112
+ ## Sage
113
+
114
+ Type a question without `!` and Sage, your Autosage assistant, answers in the transcript. Ask "why did that fail?" right after a command and it sees that command's output.
115
+
116
+ - **It looks things up by itself.** Read-only sagex commands and command help run straight away, each shown as a card with the exact command and its output.
117
+ - **It asks before changing anything.** Runs, pushes, creates, deletes, file writes and shell commands appear as an approval card with a one-line summary and the exact command: `y` once, `a` for the rest of the session, `n` no. Deletes always ask. `/permissions` lists and revokes what you've allowed.
118
+ - **It works in your workspace.** It reads, writes and edits files there (showing a diff first) and runs shell commands in your current shell. Never outside the workspace, never files that usually hold secrets.
119
+ - **It never touches secrets.** Signing in, vault and model keys, trigger secrets and `--reveal` aren't available to it; a run that needs a typed secret is handed back to you.
120
+
121
+ | Command | Action |
122
+ |---|---|
123
+ | `/sessions` | Your saved conversations; `/sessions <n>` reopens one, `/sessions delete <n>` deletes one |
124
+ | `/new` | Start a fresh conversation |
125
+ | `/model` | The models Sage can use; `/model <n or name>` or `/model free` switches |
126
+ | `/usage` | Requests and tokens today, last 7 days and all time |
127
+ | `/permissions` | What Sage may do without asking; `/permissions revoke <n>` or `revoke all` |
128
+
129
+ **Your own model.** Sage answers with Autosage's free models (a daily allowance shared with Autobot on the web) unless you pick one of your own:
130
+
131
+ ```sh
132
+ sagex create model "My Claude" --provider anthropic --model claude-sonnet-4-5 --use
133
+ ```
134
+
135
+ The API key is typed at a hidden prompt (or read with `--key-file`), stored encrypted on Autosage and never shown again. Providers: Gemini, Groq, OpenRouter, Anthropic, OpenAI, Azure OpenAI, NVIDIA NIM, or any LiteLLM-compatible endpoint (`--base-url`). `sagex use model <name>` or `--free` switches; the choice also applies to Autobot on the web.
110
136
 
111
137
  ## Commands
112
138
 
@@ -114,19 +140,20 @@ Resources can be referred to by **name or id**. An id prefix works for runs. Mos
114
140
 
115
141
  | Group | Commands | What it does |
116
142
  |---|---|---|
117
- | `auth` | `login` · `status` · `logout` | Store, check or remove your API key |
118
- | `list` | `workflow` · `script` · `run` · `trigger` · `vault` · `server` · `key` | Compact tables of your resources |
119
- | `show` | `workflow` · `script` · `run` · `trigger` · `vault` · `server` · `key` | One resource in detail; `show run --logs` prints node output, `show key --reveal` shows secrets after confirming |
143
+ | `auth` | `login` · `status` · `logout` | Sign in with your browser (or `--with-token`), see who you're signed in as, sign out |
144
+ | `list` | `workflow` · `script` · `run` · `trigger` · `vault` · `server` · `key` · `model` | Compact tables of your resources |
145
+ | `show` | `workflow` · `script` · `run` · `trigger` · `vault` · `server` · `key` · `model` | One resource in detail; `show run --logs` prints node output, `show key --reveal` shows secrets after confirming |
120
146
  | `render` | `workflow` | Draw a workflow as a flow tree (from the server, or a local file with `--file`) |
121
147
  | `run` | `script` · `workflow` | Run now and stream output live. `Ctrl+C` stops it. Pass inputs with `-p NAME=VALUE` |
122
148
  | `trigger` | `create` · `fire` · `poll` · `watch` · `invoke` · `enable` · `disable` · `regenerate` | HTTP webhooks and cron schedules: set up, fire, follow and rotate |
123
149
  | `new` | `workflow` · `script` | Scaffold a local file, ready to edit |
124
150
  | `push` | `workflow` · `script` | Create on the server from a local file, or update after confirming (scripts show a diff) |
125
151
  | `copy` | `workflow` · `script` · `run` | Download to your workspace (`--all`, or `copy run --since 7days`) |
126
- | `create` | `vault` · `server` · `key` | Create vault resources |
127
- | `update` | `vault` · `server` · `key` | Change them, or rotate a key's secret |
128
- | `rename` | `workflow` · `script` · `vault` · `server` · `key` | Rename in place |
129
- | `delete` | `workflow` · `script` · `vault` · `server` · `key` · `trigger` | Delete, after confirming |
152
+ | `create` | `vault` · `server` · `key` · `model` | Create vault resources, or add your own model |
153
+ | `update` | `vault` · `server` · `key` · `model` | Change them, or rotate a key's secret / a model's API key |
154
+ | `rename` | `workflow` · `script` · `vault` · `server` · `key` · `model` | Rename in place |
155
+ | `delete` | `workflow` · `script` · `vault` · `server` · `key` · `model` · `trigger` | Delete, after confirming |
156
+ | `use` | `model` | Choose the model Sage (and Autobot on the web) answers with, or `--free` |
130
157
  | `workspace` | `set` · `show` | Choose the local folder sagex reads from and writes to |
131
158
  | `syntax` | `trigger` · `script` · `email` · `decision` · `edge` · `decision-edge` | Print a copy-paste JSON snippet for a workflow node or edge |
132
159
 
@@ -157,19 +184,31 @@ logs/script/<id>/ saved by sagex run script
157
184
  logs/workflow/<run_id>/ saved by sagex run workflow / trigger fire
158
185
  ```
159
186
 
187
+ ## Signing in
188
+
189
+ `sagex auth login` prints a one-time code and opens Autosage in your browser. Check the code matches, approve, and you're in. On a server or over SSH, open the link on any device instead.
190
+
191
+ Each sign-in is a **session**. Your [Autosage profile](https://autosagex.web.app/profile#sagecode) lists them all, with the device, SageCode version, when it was last active, and how many commands and runs it has started, and can revoke any of them. Sessions unused for 90 days expire. `sagex auth logout` signs this machine out.
192
+
193
+ **CI and scripts:** create an **access token** on your profile and set it as `SAGEX_API_KEY`, or pipe it in with `sagex auth login --with-token`.
194
+
160
195
  ## Security
161
196
 
162
- - Your API key is stored in the **OS keychain** (Windows Credential Manager, macOS Keychain or Linux Secret Service), never in a plain file.
197
+ - Your session key is stored in the **OS keychain** (Windows Credential Manager, macOS Keychain or Linux Secret Service), never in a plain file.
198
+ - Approving a sign-in, creating tokens and revoking sessions all need you signed in to Autosage in the browser; a SageCode key can't do any of them.
163
199
  - Secrets are **never accepted as command-line flags**, so they never show up in shell history. Passwords, SSH keys and passphrases are typed at a hidden prompt or read from a file you point to.
164
200
  - Vault credentials **can't be copied** to disk, and `show key` hides secret values unless you pass `--reveal` and confirm.
165
201
  - An HTTP trigger's secret is shown **once**, when it's created or rotated.
202
+ - Model API keys are write-only: stored encrypted on Autosage, never shown or copied back.
203
+ - Sage runs nothing on its own server: every command, file change and shell command runs on your machine, in your workspace, through the same approval checks, and Sage's replies are cleaned of terminal escape sequences and unsafe links before they're shown.
166
204
 
167
205
  ## Configuration
168
206
 
169
207
  | Setting | Purpose |
170
208
  |---|---|
171
- | `SAGEX_API_KEY` | Use this API key instead of the keychain. Useful for CI or machines without a keychain |
209
+ | `SAGEX_API_KEY` | Use this access token instead of the keychain. For CI or machines without a keychain; create one on your Autosage profile |
172
210
  | `SAGEX_API_URL` | Point sagex at a different Autosage server |
211
+ | `SAGEX_AI_URL` | Point Sage at an Autobot on its own address (default: `<api url>/api/ai`) |
173
212
  | `SAGEX_DEBUG=1` | Add connection details to network errors |
174
213
  | `~/.sagex/config.json` | Saved preferences (workspace, shell) |
175
214
 
@@ -195,8 +234,9 @@ pytest
195
234
 
196
235
  ## Roadmap
197
236
 
198
- - **v1.1:** see your sagex sessions on your Autosage profile.
199
- - **v2:** Autobot in the terminal: chat, generate, run and fix, with your last command's output as context.
237
+ - **v1.1 (shipped):** sign in with your browser, and see and revoke every session on your Autosage profile.
238
+ - **v2 (shipped):** Sage in the terminal app: ask, look up, change things with your approval, files and shell in your workspace, saved conversations, your own model, usage.
239
+ - **Next:** Sage remembers your preferences across conversations, reusable skills, and connecting your own tools.
200
240
 
201
241
  ## Links
202
242
 
@@ -1,6 +1,6 @@
1
1
  # sagex
2
2
 
3
- **Autosage in your terminal.** Build, run and watch your [Autosage](https://autosagex.web.app) workflows, scripts, vaults and triggers from a full-screen terminal app or one-shot commands. Everything the web app does, minus the mouse.
3
+ **Autosage in your terminal.** Build, run and watch your [Autosage](https://autosagex.web.app) workflows, scripts, vaults and triggers from a full-screen terminal app or one-shot commands. Everything the web app does, minus the mouse, plus **Sage**: an assistant that looks things up, writes and pushes scripts, runs workflows and fixes what failed, asking you before it changes anything.
4
4
 
5
5
  [![PyPI](https://img.shields.io/pypi/v/sagex-cli)](https://pypi.org/project/sagex-cli/)
6
6
  [![Python](https://img.shields.io/pypi/pyversions/sagex-cli)](https://pypi.org/project/sagex-cli/)
@@ -16,7 +16,7 @@ $ sagex list workflow
16
16
  └──────────────────────┴──────────────────────────────────────┴──────────┘
17
17
  ```
18
18
 
19
- > **Early access.** sagex is invite-only for now. Your account needs an API key: [request one here](https://autosagex.web.app/contact).
19
+ You need an [Autosage account](https://autosagex.web.app/signup) (free).
20
20
 
21
21
  ## Install
22
22
 
@@ -32,7 +32,7 @@ curl -LsSf https://raw.githubusercontent.com/Lagnajit09/sagex/main/scripts/insta
32
32
  irm https://raw.githubusercontent.com/Lagnajit09/sagex/main/scripts/install.ps1 | iex
33
33
  ```
34
34
 
35
- The installer uses [uv](https://docs.astral.sh/uv/) to install sagex as an isolated tool, and fetches Python 3.11+ for you if needed. Set `SAGEX_VERSION=1.0.0` before running it to pin a version.
35
+ The installer uses [uv](https://docs.astral.sh/uv/) to install sagex as an isolated tool, and fetches Python 3.11+ for you if needed. Set `SAGEX_VERSION=2.0.0` before running it to pin a version.
36
36
 
37
37
  **Already have a Python tool manager?** Any of these works (Python 3.11 or newer):
38
38
 
@@ -45,8 +45,8 @@ pip install sagex-cli
45
45
  ## Quick start
46
46
 
47
47
  ```sh
48
- sagex auth login # paste your API key (stored in your OS keychain)
49
- sagex # open the terminal app
48
+ sagex auth login # approve this device in your browser
49
+ sagex # open the terminal app, then just ask Sage
50
50
  sagex list workflow # or run single commands
51
51
  sagex run workflow "Deploy" # run a workflow and follow it live, node by node
52
52
  ```
@@ -56,19 +56,44 @@ sagex run workflow "Deploy" # run a workflow and follow it live, node by node
56
56
  Run `sagex` with no arguments to open it.
57
57
 
58
58
  - **Left:** your **Resources**: Workflows, Scripts, Vault, recent Runs (with ✓ / ✗ / ⟳ status) and Triggers (● on / ○ off). Press **F3** to switch to your local **Workspace** folder instead.
59
- - **Right:** a terminal-style transcript. Start a line with `!` to run any command, such as `!sagex run workflow Deploy` or `!git status`. Output streams in live, and workflow runs draw a live node graph.
59
+ - **Right:** a terminal-style transcript. Start a line with `!` to run any command, such as `!sagex run workflow Deploy` or `!git status`. Output streams in live, and workflow runs draw a live node graph. Anything else goes to **Sage**.
60
+ - **Bottom left:** **Sage Today**: today's requests and tokens, the model Sage uses, and the free requests left.
60
61
 
61
62
  | Key | Action |
62
63
  |---|---|
63
64
  | `!command` | Run a shell or sagex command |
64
- | `Esc` | Stop the running command |
65
+ | *anything else* | Ask Sage |
66
+ | `Esc` | Stop the running command or Sage's reply |
65
67
  | `↑` / `↓` | Command history |
66
68
  | `F2` | Switch shell (PowerShell / cmd / WSL on Windows, bash / sh elsewhere) |
67
69
  | `F3` | Switch between server resources and the local workspace |
68
70
  | `F5` | Refresh |
69
71
  | `Ctrl+Q` | Quit |
70
72
 
71
- Chatting with Autobot from the terminal is coming in **sagex v2**. Until then, use Autobot in the [web app](https://autosagex.web.app/ai/autobot).
73
+ ## Sage
74
+
75
+ Type a question without `!` and Sage, your Autosage assistant, answers in the transcript. Ask "why did that fail?" right after a command and it sees that command's output.
76
+
77
+ - **It looks things up by itself.** Read-only sagex commands and command help run straight away, each shown as a card with the exact command and its output.
78
+ - **It asks before changing anything.** Runs, pushes, creates, deletes, file writes and shell commands appear as an approval card with a one-line summary and the exact command: `y` once, `a` for the rest of the session, `n` no. Deletes always ask. `/permissions` lists and revokes what you've allowed.
79
+ - **It works in your workspace.** It reads, writes and edits files there (showing a diff first) and runs shell commands in your current shell. Never outside the workspace, never files that usually hold secrets.
80
+ - **It never touches secrets.** Signing in, vault and model keys, trigger secrets and `--reveal` aren't available to it; a run that needs a typed secret is handed back to you.
81
+
82
+ | Command | Action |
83
+ |---|---|
84
+ | `/sessions` | Your saved conversations; `/sessions <n>` reopens one, `/sessions delete <n>` deletes one |
85
+ | `/new` | Start a fresh conversation |
86
+ | `/model` | The models Sage can use; `/model <n or name>` or `/model free` switches |
87
+ | `/usage` | Requests and tokens today, last 7 days and all time |
88
+ | `/permissions` | What Sage may do without asking; `/permissions revoke <n>` or `revoke all` |
89
+
90
+ **Your own model.** Sage answers with Autosage's free models (a daily allowance shared with Autobot on the web) unless you pick one of your own:
91
+
92
+ ```sh
93
+ sagex create model "My Claude" --provider anthropic --model claude-sonnet-4-5 --use
94
+ ```
95
+
96
+ The API key is typed at a hidden prompt (or read with `--key-file`), stored encrypted on Autosage and never shown again. Providers: Gemini, Groq, OpenRouter, Anthropic, OpenAI, Azure OpenAI, NVIDIA NIM, or any LiteLLM-compatible endpoint (`--base-url`). `sagex use model <name>` or `--free` switches; the choice also applies to Autobot on the web.
72
97
 
73
98
  ## Commands
74
99
 
@@ -76,19 +101,20 @@ Resources can be referred to by **name or id**. An id prefix works for runs. Mos
76
101
 
77
102
  | Group | Commands | What it does |
78
103
  |---|---|---|
79
- | `auth` | `login` · `status` · `logout` | Store, check or remove your API key |
80
- | `list` | `workflow` · `script` · `run` · `trigger` · `vault` · `server` · `key` | Compact tables of your resources |
81
- | `show` | `workflow` · `script` · `run` · `trigger` · `vault` · `server` · `key` | One resource in detail; `show run --logs` prints node output, `show key --reveal` shows secrets after confirming |
104
+ | `auth` | `login` · `status` · `logout` | Sign in with your browser (or `--with-token`), see who you're signed in as, sign out |
105
+ | `list` | `workflow` · `script` · `run` · `trigger` · `vault` · `server` · `key` · `model` | Compact tables of your resources |
106
+ | `show` | `workflow` · `script` · `run` · `trigger` · `vault` · `server` · `key` · `model` | One resource in detail; `show run --logs` prints node output, `show key --reveal` shows secrets after confirming |
82
107
  | `render` | `workflow` | Draw a workflow as a flow tree (from the server, or a local file with `--file`) |
83
108
  | `run` | `script` · `workflow` | Run now and stream output live. `Ctrl+C` stops it. Pass inputs with `-p NAME=VALUE` |
84
109
  | `trigger` | `create` · `fire` · `poll` · `watch` · `invoke` · `enable` · `disable` · `regenerate` | HTTP webhooks and cron schedules: set up, fire, follow and rotate |
85
110
  | `new` | `workflow` · `script` | Scaffold a local file, ready to edit |
86
111
  | `push` | `workflow` · `script` | Create on the server from a local file, or update after confirming (scripts show a diff) |
87
112
  | `copy` | `workflow` · `script` · `run` | Download to your workspace (`--all`, or `copy run --since 7days`) |
88
- | `create` | `vault` · `server` · `key` | Create vault resources |
89
- | `update` | `vault` · `server` · `key` | Change them, or rotate a key's secret |
90
- | `rename` | `workflow` · `script` · `vault` · `server` · `key` | Rename in place |
91
- | `delete` | `workflow` · `script` · `vault` · `server` · `key` · `trigger` | Delete, after confirming |
113
+ | `create` | `vault` · `server` · `key` · `model` | Create vault resources, or add your own model |
114
+ | `update` | `vault` · `server` · `key` · `model` | Change them, or rotate a key's secret / a model's API key |
115
+ | `rename` | `workflow` · `script` · `vault` · `server` · `key` · `model` | Rename in place |
116
+ | `delete` | `workflow` · `script` · `vault` · `server` · `key` · `model` · `trigger` | Delete, after confirming |
117
+ | `use` | `model` | Choose the model Sage (and Autobot on the web) answers with, or `--free` |
92
118
  | `workspace` | `set` · `show` | Choose the local folder sagex reads from and writes to |
93
119
  | `syntax` | `trigger` · `script` · `email` · `decision` · `edge` · `decision-edge` | Print a copy-paste JSON snippet for a workflow node or edge |
94
120
 
@@ -119,19 +145,31 @@ logs/script/<id>/ saved by sagex run script
119
145
  logs/workflow/<run_id>/ saved by sagex run workflow / trigger fire
120
146
  ```
121
147
 
148
+ ## Signing in
149
+
150
+ `sagex auth login` prints a one-time code and opens Autosage in your browser. Check the code matches, approve, and you're in. On a server or over SSH, open the link on any device instead.
151
+
152
+ Each sign-in is a **session**. Your [Autosage profile](https://autosagex.web.app/profile#sagecode) lists them all, with the device, SageCode version, when it was last active, and how many commands and runs it has started, and can revoke any of them. Sessions unused for 90 days expire. `sagex auth logout` signs this machine out.
153
+
154
+ **CI and scripts:** create an **access token** on your profile and set it as `SAGEX_API_KEY`, or pipe it in with `sagex auth login --with-token`.
155
+
122
156
  ## Security
123
157
 
124
- - Your API key is stored in the **OS keychain** (Windows Credential Manager, macOS Keychain or Linux Secret Service), never in a plain file.
158
+ - Your session key is stored in the **OS keychain** (Windows Credential Manager, macOS Keychain or Linux Secret Service), never in a plain file.
159
+ - Approving a sign-in, creating tokens and revoking sessions all need you signed in to Autosage in the browser; a SageCode key can't do any of them.
125
160
  - Secrets are **never accepted as command-line flags**, so they never show up in shell history. Passwords, SSH keys and passphrases are typed at a hidden prompt or read from a file you point to.
126
161
  - Vault credentials **can't be copied** to disk, and `show key` hides secret values unless you pass `--reveal` and confirm.
127
162
  - An HTTP trigger's secret is shown **once**, when it's created or rotated.
163
+ - Model API keys are write-only: stored encrypted on Autosage, never shown or copied back.
164
+ - Sage runs nothing on its own server: every command, file change and shell command runs on your machine, in your workspace, through the same approval checks, and Sage's replies are cleaned of terminal escape sequences and unsafe links before they're shown.
128
165
 
129
166
  ## Configuration
130
167
 
131
168
  | Setting | Purpose |
132
169
  |---|---|
133
- | `SAGEX_API_KEY` | Use this API key instead of the keychain. Useful for CI or machines without a keychain |
170
+ | `SAGEX_API_KEY` | Use this access token instead of the keychain. For CI or machines without a keychain; create one on your Autosage profile |
134
171
  | `SAGEX_API_URL` | Point sagex at a different Autosage server |
172
+ | `SAGEX_AI_URL` | Point Sage at an Autobot on its own address (default: `<api url>/api/ai`) |
135
173
  | `SAGEX_DEBUG=1` | Add connection details to network errors |
136
174
  | `~/.sagex/config.json` | Saved preferences (workspace, shell) |
137
175
 
@@ -157,8 +195,9 @@ pytest
157
195
 
158
196
  ## Roadmap
159
197
 
160
- - **v1.1:** see your sagex sessions on your Autosage profile.
161
- - **v2:** Autobot in the terminal: chat, generate, run and fix, with your last command's output as context.
198
+ - **v1.1 (shipped):** sign in with your browser, and see and revoke every session on your Autosage profile.
199
+ - **v2 (shipped):** Sage in the terminal app: ask, look up, change things with your approval, files and shell in your workspace, saved conversations, your own model, usage.
200
+ - **Next:** Sage remembers your preferences across conversations, reusable skills, and connecting your own tools.
162
201
 
163
202
  ## Links
164
203
 
@@ -48,6 +48,7 @@ dependencies = [
48
48
  "keyring>=25.7.0,<26",
49
49
  "typer>=0.27.2,<0.28",
50
50
  "cron-descriptor>=2.1.0,<3",
51
+ "websockets>=14,<17", # Sage, the terminal agent (one socket per conversation)
51
52
  ]
52
53
 
53
54
  [project.optional-dependencies]
@@ -58,7 +59,7 @@ dev = [
58
59
  ]
59
60
 
60
61
  [project.urls]
61
- Homepage = "https://github.com/Lagnajit09/sagex"
62
+ Homepage = "https://sagecode.web.app"
62
63
  Documentation = "https://autosagexdocs.web.app"
63
64
  Repository = "https://github.com/Lagnajit09/sagex"
64
65
  Issues = "https://github.com/Lagnajit09/sagex/issues"
@@ -1,3 +1,3 @@
1
1
  """sagex — Autosage in your terminal."""
2
2
 
3
- __version__ = "1.0.0"
3
+ __version__ = "2.0.0"