@deepraxis/cli 0.1.1-dev.f0ef747 → 0.2.0-dev.3c36146

package/README.md

@@ -19,15 +19,27 @@ The official command line for [知行云 Praxis](https://deepraxis.com), the clo
 ```sh
 npm install -g @deepraxis/cli
 praxis login
-praxis model chat completion create --model deepseek-flash \
+praxis api model chat completion create --model deepseek-flash \
   --data '{"messages":[{"role":"user","content":"Hello!"}]}'
 ```
 
-Every operation of the Praxis API is a command: about 350 of them across models, agents,
+Every operation of the Praxis API is a command under `praxis api`: about 350 of them across models, agents,
 sandboxes, cloud browsers, web search, databases, knowledge bases, files, media, automation
 and hosted applications. The command tree is generated from the same contract as the API and
 the SDK, so a new API capability reaches the CLI on the day it ships.
 
+## Build and deploy an application
+
+```sh
+praxis app create my-app         # standard template, dependencies installed
+cd my-app && praxis app deploy   # build, publish, create declared secrets, health check, print the URL
+praxis app rollback              # deploy the previous version again
+```
+
+`praxis.jsonc` at the project root names the app and may declare `"secrets": {"SESSION_SECRET": "generate"}`
+(created once, kept by every later deploy) and `"healthcheck": "/api/health"` (a failing check fails the deploy).
+In computers and sandboxes the CLI signs in with `PRAXIS_API_TOKEN`; `PRAXIS_API_KEY` takes precedence when both are set.
+
 ## Why Praxis CLI
 
 - **One account, every capability.** Chat with models from many providers, start a sandbox,
@@ -36,7 +48,7 @@ the SDK, so a new API capability reaches the CLI on the day it ships.
   AI coding agent runs it, and clean JSON in scripts. The CLI picks the mode by itself.
 - **Signs in through the browser.** `praxis login` approves the session in your browser and
   keeps the credential in the system keychain, never in a dotfile when a keychain exists.
-- **Predictable grammar.** `praxis <domain> <resource> <verb> [id]`, the same shape everywhere,
+- **Predictable grammar.** `praxis api <domain> <resource> <verb> [id]`, the same shape everywhere,
   with `--help` on every level.
 
 ## Install
@@ -68,7 +80,7 @@ Belong to several organizations? Every call runs in the active one:
 ```sh
 praxis org list
 praxis org switch <organization_id>
-praxis model list --org <organization_id>   # just this call
+praxis api model list --org <organization_id>   # just this call
 ```
 
 For CI and other headless environments, create an API key in the
@@ -84,12 +96,12 @@ export PRAXIS_API_KEY=<your-api-key>
 ### Models
 
 ```sh
-praxis model list
-praxis model chat completion create --model deepseek-flash \
+praxis api model list
+praxis api model chat completion create --model deepseek-flash \
   --data '{"messages":[{"role":"user","content":"A haiku"}]}'
-praxis model embedding create --model <embedding_model> \
+praxis api model embedding create --model <embedding_model> \
   --data '{"input":"hello world"}'
-praxis model image generation create --model <image_model> \
+praxis api model image generation create --model <image_model> \
   --prompt "a lighthouse at dawn"
 ```
 
@@ -98,53 +110,56 @@ praxis model image generation create --model <image_model> \
 Define an agent once, then talk to it in sessions:
 
 ```sh
-praxis agent create --data '{
+praxis api agent create --data '{
   "name": "helper",
   "model": {"id": "deepseek-flash"},
   "tools": [{"type": "agent_toolset_20260401"}]
 }'
-praxis agent session create --data '{"agent": "<agent_id>"}'
-praxis agent session event send <session_id> --data '{
+praxis api agent session create --data '{"agent": "<agent_id>"}'
+praxis api agent session event send <session_id> --data '{
   "events": [{
     "type": "user.message",
     "content": [{"type": "text", "text": "What can you do?"}]
   }]
 }'
-praxis agent session event stream --session <session_id>
+praxis api agent session event stream --session <session_id>
 ```
 
 ### Sandboxes
 
 ```sh
-praxis sandbox create --template-id base
-praxis sandbox command run <sandbox_id> \
+praxis api sandbox create --template-id base
+praxis api sandbox command run <sandbox_id> \
   --cmd "python3 -c 'print(6 * 7)'"
-praxis sandbox delete <sandbox_id> --yes
+praxis api sandbox delete <sandbox_id> --yes
 ```
 
 ### Search, data and automation
 
 ```sh
-praxis search create --query "AI agent frameworks" --max-results 5
-praxis database create --name notes
-praxis automation run create --data '{
+praxis api search create --query "AI agent frameworks" --max-results 5
+praxis api database create --name notes
+praxis api automation run create --data '{
   "source": "export default async (i) => ({ answer: i.n + 1 })",
   "language": "ts", "input": {"n": 41}, "wait": 30
 }'
 ```
 
-Browse everything with `praxis --help`, `praxis <domain> --help`, or the full
+Browse everything with `praxis --help`, `praxis api --help`, `praxis api <domain> --help`, or the full
 [command reference](https://unpkg.com/@deepraxis/cli/COMMANDS.md) that ships in the package.
 
 ## How commands work
 
+There are two layers. Top-level commands are workflows and session commands (`login`, `logout`,
+`whoami`, `org`, `skill`). Every API operation lives under `praxis api`, so the two never collide.
+
 ```text
-praxis  sandbox  command  run  sbx_123  --cmd "ls"  --json
-        domain   resource verb target   options     global
+praxis api  sandbox  command  run  sbx_123  --cmd "ls"  --json
+            domain   resource verb target   options     global
 ```
 
 - **One target, positionally.** The object a command acts on comes right after the verb. Parent
-  objects are options: `praxis database table list --database <database_id>`.
+  objects are options: `praxis api database table list --database <database_id>`.
 - **Request bodies.** Simple fields have their own options. Anything else goes in `--data`, as
   inline JSON, a file (`--data @body.json`) or stdin (`--data -`). Field options win over the
   same field in `--data`.
@@ -152,7 +167,7 @@ praxis  sandbox  command  run  sbx_123  --cmd "ls"  --json
   resumes from a page you saved.
 - **Safety.** Deleting and other destructive commands ask for confirmation, or need `--yes`
   when no one can answer, for example in a script.
-- **Escape hatch.** `praxis api <METHOD> <path> [--data …]` calls any endpoint with your
+- **Escape hatch.** `praxis api <METHOD> <path> [--data …]` (an uppercase method, such as `praxis api GET /model/v1/models`) calls any endpoint with your
   current credential, including ones that are new since your installed version.
 
 ## Output for people, AI agents and scripts
@@ -167,7 +182,7 @@ Errors follow the same rule. In JSON they are one object on stderr with `code`,
 `hint`, `status` and `request_id`, so a script or an agent can tell a typo from a quota limit.
 
 ```sh
-praxis model list --json | jq -r '.data[].id'
+praxis api model list --json | jq -r '.data[].id'
 ```
 
 ## Teach your AI agent to use Praxis