mouter-cli 0.1.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.
- mouter_cli-0.1.0/PKG-INFO +213 -0
- mouter_cli-0.1.0/README.md +204 -0
- mouter_cli-0.1.0/pyproject.toml +47 -0
- mouter_cli-0.1.0/pyproject.toml.orig +40 -0
- mouter_cli-0.1.0/src/mouter_cli/__init__.py +3 -0
- mouter_cli-0.1.0/src/mouter_cli/cli.py +417 -0
- mouter_cli-0.1.0/src/mouter_cli/client.py +320 -0
- mouter_cli-0.1.0/src/mouter_cli/config.py +56 -0
- mouter_cli-0.1.0/src/mouter_cli/errors.py +22 -0
- mouter_cli-0.1.0/src/mouter_cli/oauth.py +444 -0
- mouter_cli-0.1.0/src/mouter_cli/storage.py +285 -0
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
Metadata-Version: 2.3
|
|
2
|
+
Name: mouter-cli
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Discover and call Mouter tools from a terminal or AI client
|
|
5
|
+
Requires-Dist: httpx>=0.28,<1
|
|
6
|
+
Requires-Dist: simplejson>=3.19,<4
|
|
7
|
+
Requires-Python: >=3.12
|
|
8
|
+
Description-Content-Type: text/markdown
|
|
9
|
+
|
|
10
|
+
# Mouter CLI
|
|
11
|
+
|
|
12
|
+
A small HTTP client for discovering Mouter tools and submitting paid tasks. Python 3.12+
|
|
13
|
+
with HTTPX and local credential files; no backend runtime, local AI model, database or daemon.
|
|
14
|
+
|
|
15
|
+
## Install
|
|
16
|
+
|
|
17
|
+
After publication:
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
uv tool install mouter-cli
|
|
21
|
+
mouter --version
|
|
22
|
+
uv tool upgrade mouter-cli
|
|
23
|
+
# Run without a permanent tool installation:
|
|
24
|
+
uvx --from mouter-cli mouter --help
|
|
25
|
+
# Pin a version for reproducible automation:
|
|
26
|
+
uvx --from mouter-cli==0.1.0 mouter --version
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Before publication, build and install the wheel:
|
|
30
|
+
|
|
31
|
+
```sh
|
|
32
|
+
uv build --project packages/mouter-cli --out-dir /tmp/mouter-cli-dist
|
|
33
|
+
uv tool install /tmp/mouter-cli-dist/mouter_cli-0.1.0-py3-none-any.whl
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
The default API origin is `https://mouter.ai`. Override it with `MOUTER_BASE_URL` or
|
|
37
|
+
`--base-url`. HTTPS is required except for literal loopback IPs used in development.
|
|
38
|
+
Saved credentials are isolated by normalized origin. Redirects are never followed.
|
|
39
|
+
The HTTP client does not inherit proxy configuration or transport debug logging.
|
|
40
|
+
|
|
41
|
+
## Authenticate
|
|
42
|
+
|
|
43
|
+
The default login opens your browser to sign in and authorize Mouter CLI:
|
|
44
|
+
|
|
45
|
+
```sh
|
|
46
|
+
mouter auth login
|
|
47
|
+
mouter auth status
|
|
48
|
+
mouter balance
|
|
49
|
+
mouter usage --limit 10
|
|
50
|
+
mouter tasks billing TASK_ID
|
|
51
|
+
mouter auth logout
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Browser login uses authorization code + PKCE with a temporary loopback callback. It never
|
|
55
|
+
copies browser cookies or asks the AI client for your password. `--no-browser` prints a
|
|
56
|
+
URL to open on the same machine; `--login-timeout` defaults to 180 seconds (maximum 600).
|
|
57
|
+
Remote servers/CI should use an API key instead of a browser callback.
|
|
58
|
+
|
|
59
|
+
CLI access/refresh tokens and explicitly saved API keys are stored as plaintext JSON files,
|
|
60
|
+
isolated by API origin: `$MOUTER_STATE_DIR/credentials/<origin-sha256>.json`. Without an override,
|
|
61
|
+
the state directory is `$XDG_STATE_HOME/mouter` (default `~/.local/state/mouter`) on POSIX,
|
|
62
|
+
or `%LOCALAPPDATA%\Mouter` on Windows. On POSIX the credentials directory is mode 0700 and
|
|
63
|
+
files are mode 0600; Windows uses the user profile's inherited permissions. Writes use a
|
|
64
|
+
private temporary file and atomic replacement. Keep this directory out of shared folders
|
|
65
|
+
and source control. The CLI never accesses the system keychain. Earlier test builds' system
|
|
66
|
+
credentials are not migrated: sign in again and revoke any old authorization on the website.
|
|
67
|
+
Refresh rotation is serialized across processes. A command stays bound to its
|
|
68
|
+
original authorization; changing accounts in another terminal cannot redirect its calls.
|
|
69
|
+
Waiting deadlines also bound refresh and lock waits. `auth logout` revokes the saved CLI
|
|
70
|
+
session's token family on the server before deleting it locally. On revocation/network
|
|
71
|
+
failure, credentials remain saved so logout can be retried. Website sessions and unrelated
|
|
72
|
+
CLI authorizations are unaffected. Log out before replacing a saved browser authorization.
|
|
73
|
+
|
|
74
|
+
For automation, create a restricted API key on the Mouter website and configure
|
|
75
|
+
`MOUTER_API_KEY` in your secret environment. Alternatively:
|
|
76
|
+
|
|
77
|
+
```sh
|
|
78
|
+
mouter auth login --api-key # hidden terminal prompt
|
|
79
|
+
# Or pipe a key from a secret manager:
|
|
80
|
+
# secret-manager-command | mouter auth login --key-stdin
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Environment API keys take priority over saved credentials and are never persisted.
|
|
84
|
+
Do not put keys in command arguments or AI prompts. Local storage errors fail explicitly;
|
|
85
|
+
an environment API key works without reading the credential file, including on headless hosts. Logout cannot unset the caller's environment. Saved API keys are
|
|
86
|
+
only deleted locally by logout; revoke those keys separately on the website.
|
|
87
|
+
|
|
88
|
+
`balance` shows account available/reserved wallet quota plus the current credential's
|
|
89
|
+
limit, spent, reserved and remaining quota. A null credential limit/remaining means no
|
|
90
|
+
credential-specific cap; it does not grant wallet credit. Raw quota is the smallest credit
|
|
91
|
+
accounting unit (10,000 quota per credit); it does not express the actual cash paid for credits.
|
|
92
|
+
`usage` is newest first, defaults to 10 rows (maximum 100), and supports
|
|
93
|
+
`--cursor` pagination. It includes only tasks submitted by the current API key or OAuth
|
|
94
|
+
authorization, never other credentials' spending details or task inputs. Pending reservation
|
|
95
|
+
is distinct from settled charges. Cursors cannot be reused by another credential.
|
|
96
|
+
|
|
97
|
+
`tasks billing TASK_ID` is a free, read-only query for that task's consumption using the
|
|
98
|
+
original credential. It returns `task_id`, `tool_key`, `task_status`, `billing_status`,
|
|
99
|
+
`unit`, `reserved_amount`, `charged_amount`, and `settled_at`. Both amounts are JSON numbers
|
|
100
|
+
in credits, matching Web Credits, with `unit="credit"` and up to four decimal places.
|
|
101
|
+
For example, 2,001 raw quota becomes 0.2001 credits. Top-up prices do not change this unit;
|
|
102
|
+
the charge does not express a cash payment. This response does not include `quota_per_usd`
|
|
103
|
+
or raw quota fields. A `pending` charge is `null`,
|
|
104
|
+
not zero. `settled` includes successful free tasks; `not_charged` means zero charge
|
|
105
|
+
after failure, cancellation or timeout. `settled_at` is UTC Unix seconds for successful
|
|
106
|
+
settlement, otherwise null. Result expiry does not remove billing history.
|
|
107
|
+
The CLI preserves exact decimal JSON numbers, including the maximum 900,719,925,474.0991
|
|
108
|
+
credits. Consumers doing exact accounting must use decimal JSON parsing; ordinary binary
|
|
109
|
+
floating-point parsers can round large amounts. The CLI prints numbers, never numeric strings.
|
|
110
|
+
Use this command on request to report a task's charge. Do not automatically query prices
|
|
111
|
+
before execution or billing after execution. If billing fails or
|
|
112
|
+
OAuth lacks permission, preserve the task result and report the cost as unavailable.
|
|
113
|
+
Retry reads only; never resubmit paid work to recover billing information. API errors use
|
|
114
|
+
the existing exit codes. Reauthorizing may create a different grant; it does not grant
|
|
115
|
+
access to the previous grant's tasks.
|
|
116
|
+
|
|
117
|
+
OAuth financial reads require explicit `billing:read` consent. CLI browser login requests
|
|
118
|
+
`tools:execute tasks:read billing:read`; existing OAuth clients keep their original default
|
|
119
|
+
two scopes. Backend REST and MCP share the configured Mouter resource identifier (currently
|
|
120
|
+
commonly `/mcp`); REST discovery is also available at
|
|
121
|
+
`/.well-known/oauth-protected-resource/v1`. The CLI uses the advertised identifier instead
|
|
122
|
+
of inventing another token audience. Neither credential type can manage the account via
|
|
123
|
+
these read endpoints.
|
|
124
|
+
|
|
125
|
+
## Discover, inspect and call
|
|
126
|
+
|
|
127
|
+
```sh
|
|
128
|
+
mouter catalog categories
|
|
129
|
+
mouter catalog search '播放量' --limit 10
|
|
130
|
+
mouter catalog list --category social --limit 10
|
|
131
|
+
mouter catalog get media_stats
|
|
132
|
+
mouter catalog price media_stats
|
|
133
|
+
mouter call media_stats --input @input.json
|
|
134
|
+
mouter call media_stats --input @input.json --wait --wait-timeout 300
|
|
135
|
+
mouter tasks get TASK_ID
|
|
136
|
+
mouter tasks wait TASK_ID --wait-timeout 300
|
|
137
|
+
mouter agent-guide --human
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Catalog queries are public and never require credentials. Search matches a literal,
|
|
141
|
+
case-insensitive substring in the tool key, name or description. A phrase is not an OR
|
|
142
|
+
query, and tool-key ordering is not a relevance ranking. Defaults: 10 results, active tools.
|
|
143
|
+
Use `--status all` or `--status disabled` explicitly. Follow `page.next_cursor` with
|
|
144
|
+
`--cursor`; the cursor is bound to the query, category and status. No automatic full scan.
|
|
145
|
+
Category counts include both active and disabled tools. Only `catalog get` loads schemas.
|
|
146
|
+
Visibility is not permission to execute; server checks are authoritative.
|
|
147
|
+
|
|
148
|
+
Use `catalog get TOOL_KEY` directly when the public key is known. Search does not give
|
|
149
|
+
exact key matches a ranking bonus. A platform name such as `TikTok` can span many pages;
|
|
150
|
+
prefer a distinctive capability substring. For example, `视频生成` and `生成视频` are different
|
|
151
|
+
literal queries: rewrite the keyword or browse `--category video` after an empty result.
|
|
152
|
+
Do not concatenate keywords as if this were an AND or semantic query.
|
|
153
|
+
|
|
154
|
+
AI clients with shell access should use `agent-guide`: understand the user, choose short
|
|
155
|
+
keywords or a category, inspect a few candidates, fetch selected schemas, then call.
|
|
156
|
+
At most two keyword rewrites are suggested before browsing or clarifying the need.
|
|
157
|
+
The CLI does not make AI calls. Website search and its taxonomy remain separate.
|
|
158
|
+
|
|
159
|
+
`--input` accepts a JSON object, `@file.json`, or `@-` for UTF-8 stdin, at most 64 KiB.
|
|
160
|
+
Duplicate fields and non-finite numbers are rejected. Business validation happens on the
|
|
161
|
+
server. Prices reflect the current key's user pricing; a quote does not freeze charges.
|
|
162
|
+
|
|
163
|
+
## Recovery and task semantics
|
|
164
|
+
|
|
165
|
+
Each call creates an idempotency key and a non-secret local receipt **before** submitting.
|
|
166
|
+
Use `--idempotency-key KEY` to supply your own key. Receipts contain origin, tool, input
|
|
167
|
+
hash, creation time, idempotency key, and task ID when known; never the API key or input.
|
|
168
|
+
Location: `$MOUTER_STATE_DIR/receipts`, or the platform's user state directory. POSIX files
|
|
169
|
+
are created with mode 0600. There is no background cleanup or local task runner.
|
|
170
|
+
|
|
171
|
+
POST is never automatically retried. If `SUBMISSION_UNKNOWN` is returned, the server may
|
|
172
|
+
have accepted the task: retry with the **same key, credential authorization, tool and input within 24
|
|
173
|
+
hours**. The server rejects different input for the same key. After the window expires,
|
|
174
|
+
inspect the original task on the website rather than automatically starting another.
|
|
175
|
+
Local receipts also block accidental expired-key or different-input reuse. A missing
|
|
176
|
+
receipt does not extend the server's window; the caller must retain the original key/time.
|
|
177
|
+
|
|
178
|
+
HTTP requests have a 30-second operation budget with a 5-second connect timeout. GET may
|
|
179
|
+
retry twice within that budget and honors Retry-After. Waiting uses 1, 2, 4, then at most
|
|
180
|
+
5 seconds between polls, with small jitter. `--wait-timeout` defaults to 300 seconds and
|
|
181
|
+
bounds polling. Timeout or Ctrl+C stops the client only; **it does not cancel the task**.
|
|
182
|
+
Resume by task ID using the original credential authorization. OAuth token refresh keeps
|
|
183
|
+
the same authorization and receipt identity; logging in again creates a separate scope. Task reads are credential-scoped, so a
|
|
184
|
+
replacement key does not automatically grant access to old tasks.
|
|
185
|
+
|
|
186
|
+
`submitted`, `queued` and `in_progress` are nonterminal. `succeeded`, `failed`, `timed_out`
|
|
187
|
+
and `canceled` are terminal. A succeeded task with `result: null` has no currently available
|
|
188
|
+
result (for example because of retention); do not resubmit automatically.
|
|
189
|
+
|
|
190
|
+
## Output contract
|
|
191
|
+
|
|
192
|
+
Normal commands write one JSON document to stdout:
|
|
193
|
+
`code`, `message`, `data`, `request_id`, with optional `page` and `meta`.
|
|
194
|
+
Call metadata contains `idempotency_key`, `replayed`, and `receipt_saved`.
|
|
195
|
+
`--human` indents JSON, or prints the agent guide as text. JSON escapes control characters.
|
|
196
|
+
Help/version are normal terminal text. Prompts and nonessential diagnostics use stderr.
|
|
197
|
+
`--verbose` shows only method, public route, HTTP status and request ID, never raw
|
|
198
|
+
headers, credentials, request inputs, proxy responses or internal routing diagnostics.
|
|
199
|
+
|
|
200
|
+
| Exit | Meaning |
|
|
201
|
+
|---|---|
|
|
202
|
+
| 0 | Command succeeded (a submission can still be pending) |
|
|
203
|
+
| 1 | Unexpected client error |
|
|
204
|
+
| 2 | Invalid local arguments/input |
|
|
205
|
+
| 3 | Authentication, permission or credential-store error |
|
|
206
|
+
| 4 | Network, API or protocol error |
|
|
207
|
+
| 5 | A waited task failed, timed out on the server, or was canceled |
|
|
208
|
+
| 6 | Client wait deadline reached |
|
|
209
|
+
| 7 | Submission acceptance is unknown |
|
|
210
|
+
| 130 | Client interrupted |
|
|
211
|
+
|
|
212
|
+
`tasks get` exits 0 when it successfully reads a failed task; inspect `data.status`.
|
|
213
|
+
`tasks wait` and `call --wait` use exit 5 for an unsuccessful terminal task.
|
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
# Mouter CLI
|
|
2
|
+
|
|
3
|
+
A small HTTP client for discovering Mouter tools and submitting paid tasks. Python 3.12+
|
|
4
|
+
with HTTPX and local credential files; no backend runtime, local AI model, database or daemon.
|
|
5
|
+
|
|
6
|
+
## Install
|
|
7
|
+
|
|
8
|
+
After publication:
|
|
9
|
+
|
|
10
|
+
```sh
|
|
11
|
+
uv tool install mouter-cli
|
|
12
|
+
mouter --version
|
|
13
|
+
uv tool upgrade mouter-cli
|
|
14
|
+
# Run without a permanent tool installation:
|
|
15
|
+
uvx --from mouter-cli mouter --help
|
|
16
|
+
# Pin a version for reproducible automation:
|
|
17
|
+
uvx --from mouter-cli==0.1.0 mouter --version
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Before publication, build and install the wheel:
|
|
21
|
+
|
|
22
|
+
```sh
|
|
23
|
+
uv build --project packages/mouter-cli --out-dir /tmp/mouter-cli-dist
|
|
24
|
+
uv tool install /tmp/mouter-cli-dist/mouter_cli-0.1.0-py3-none-any.whl
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
The default API origin is `https://mouter.ai`. Override it with `MOUTER_BASE_URL` or
|
|
28
|
+
`--base-url`. HTTPS is required except for literal loopback IPs used in development.
|
|
29
|
+
Saved credentials are isolated by normalized origin. Redirects are never followed.
|
|
30
|
+
The HTTP client does not inherit proxy configuration or transport debug logging.
|
|
31
|
+
|
|
32
|
+
## Authenticate
|
|
33
|
+
|
|
34
|
+
The default login opens your browser to sign in and authorize Mouter CLI:
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
mouter auth login
|
|
38
|
+
mouter auth status
|
|
39
|
+
mouter balance
|
|
40
|
+
mouter usage --limit 10
|
|
41
|
+
mouter tasks billing TASK_ID
|
|
42
|
+
mouter auth logout
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Browser login uses authorization code + PKCE with a temporary loopback callback. It never
|
|
46
|
+
copies browser cookies or asks the AI client for your password. `--no-browser` prints a
|
|
47
|
+
URL to open on the same machine; `--login-timeout` defaults to 180 seconds (maximum 600).
|
|
48
|
+
Remote servers/CI should use an API key instead of a browser callback.
|
|
49
|
+
|
|
50
|
+
CLI access/refresh tokens and explicitly saved API keys are stored as plaintext JSON files,
|
|
51
|
+
isolated by API origin: `$MOUTER_STATE_DIR/credentials/<origin-sha256>.json`. Without an override,
|
|
52
|
+
the state directory is `$XDG_STATE_HOME/mouter` (default `~/.local/state/mouter`) on POSIX,
|
|
53
|
+
or `%LOCALAPPDATA%\Mouter` on Windows. On POSIX the credentials directory is mode 0700 and
|
|
54
|
+
files are mode 0600; Windows uses the user profile's inherited permissions. Writes use a
|
|
55
|
+
private temporary file and atomic replacement. Keep this directory out of shared folders
|
|
56
|
+
and source control. The CLI never accesses the system keychain. Earlier test builds' system
|
|
57
|
+
credentials are not migrated: sign in again and revoke any old authorization on the website.
|
|
58
|
+
Refresh rotation is serialized across processes. A command stays bound to its
|
|
59
|
+
original authorization; changing accounts in another terminal cannot redirect its calls.
|
|
60
|
+
Waiting deadlines also bound refresh and lock waits. `auth logout` revokes the saved CLI
|
|
61
|
+
session's token family on the server before deleting it locally. On revocation/network
|
|
62
|
+
failure, credentials remain saved so logout can be retried. Website sessions and unrelated
|
|
63
|
+
CLI authorizations are unaffected. Log out before replacing a saved browser authorization.
|
|
64
|
+
|
|
65
|
+
For automation, create a restricted API key on the Mouter website and configure
|
|
66
|
+
`MOUTER_API_KEY` in your secret environment. Alternatively:
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
mouter auth login --api-key # hidden terminal prompt
|
|
70
|
+
# Or pipe a key from a secret manager:
|
|
71
|
+
# secret-manager-command | mouter auth login --key-stdin
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Environment API keys take priority over saved credentials and are never persisted.
|
|
75
|
+
Do not put keys in command arguments or AI prompts. Local storage errors fail explicitly;
|
|
76
|
+
an environment API key works without reading the credential file, including on headless hosts. Logout cannot unset the caller's environment. Saved API keys are
|
|
77
|
+
only deleted locally by logout; revoke those keys separately on the website.
|
|
78
|
+
|
|
79
|
+
`balance` shows account available/reserved wallet quota plus the current credential's
|
|
80
|
+
limit, spent, reserved and remaining quota. A null credential limit/remaining means no
|
|
81
|
+
credential-specific cap; it does not grant wallet credit. Raw quota is the smallest credit
|
|
82
|
+
accounting unit (10,000 quota per credit); it does not express the actual cash paid for credits.
|
|
83
|
+
`usage` is newest first, defaults to 10 rows (maximum 100), and supports
|
|
84
|
+
`--cursor` pagination. It includes only tasks submitted by the current API key or OAuth
|
|
85
|
+
authorization, never other credentials' spending details or task inputs. Pending reservation
|
|
86
|
+
is distinct from settled charges. Cursors cannot be reused by another credential.
|
|
87
|
+
|
|
88
|
+
`tasks billing TASK_ID` is a free, read-only query for that task's consumption using the
|
|
89
|
+
original credential. It returns `task_id`, `tool_key`, `task_status`, `billing_status`,
|
|
90
|
+
`unit`, `reserved_amount`, `charged_amount`, and `settled_at`. Both amounts are JSON numbers
|
|
91
|
+
in credits, matching Web Credits, with `unit="credit"` and up to four decimal places.
|
|
92
|
+
For example, 2,001 raw quota becomes 0.2001 credits. Top-up prices do not change this unit;
|
|
93
|
+
the charge does not express a cash payment. This response does not include `quota_per_usd`
|
|
94
|
+
or raw quota fields. A `pending` charge is `null`,
|
|
95
|
+
not zero. `settled` includes successful free tasks; `not_charged` means zero charge
|
|
96
|
+
after failure, cancellation or timeout. `settled_at` is UTC Unix seconds for successful
|
|
97
|
+
settlement, otherwise null. Result expiry does not remove billing history.
|
|
98
|
+
The CLI preserves exact decimal JSON numbers, including the maximum 900,719,925,474.0991
|
|
99
|
+
credits. Consumers doing exact accounting must use decimal JSON parsing; ordinary binary
|
|
100
|
+
floating-point parsers can round large amounts. The CLI prints numbers, never numeric strings.
|
|
101
|
+
Use this command on request to report a task's charge. Do not automatically query prices
|
|
102
|
+
before execution or billing after execution. If billing fails or
|
|
103
|
+
OAuth lacks permission, preserve the task result and report the cost as unavailable.
|
|
104
|
+
Retry reads only; never resubmit paid work to recover billing information. API errors use
|
|
105
|
+
the existing exit codes. Reauthorizing may create a different grant; it does not grant
|
|
106
|
+
access to the previous grant's tasks.
|
|
107
|
+
|
|
108
|
+
OAuth financial reads require explicit `billing:read` consent. CLI browser login requests
|
|
109
|
+
`tools:execute tasks:read billing:read`; existing OAuth clients keep their original default
|
|
110
|
+
two scopes. Backend REST and MCP share the configured Mouter resource identifier (currently
|
|
111
|
+
commonly `/mcp`); REST discovery is also available at
|
|
112
|
+
`/.well-known/oauth-protected-resource/v1`. The CLI uses the advertised identifier instead
|
|
113
|
+
of inventing another token audience. Neither credential type can manage the account via
|
|
114
|
+
these read endpoints.
|
|
115
|
+
|
|
116
|
+
## Discover, inspect and call
|
|
117
|
+
|
|
118
|
+
```sh
|
|
119
|
+
mouter catalog categories
|
|
120
|
+
mouter catalog search '播放量' --limit 10
|
|
121
|
+
mouter catalog list --category social --limit 10
|
|
122
|
+
mouter catalog get media_stats
|
|
123
|
+
mouter catalog price media_stats
|
|
124
|
+
mouter call media_stats --input @input.json
|
|
125
|
+
mouter call media_stats --input @input.json --wait --wait-timeout 300
|
|
126
|
+
mouter tasks get TASK_ID
|
|
127
|
+
mouter tasks wait TASK_ID --wait-timeout 300
|
|
128
|
+
mouter agent-guide --human
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Catalog queries are public and never require credentials. Search matches a literal,
|
|
132
|
+
case-insensitive substring in the tool key, name or description. A phrase is not an OR
|
|
133
|
+
query, and tool-key ordering is not a relevance ranking. Defaults: 10 results, active tools.
|
|
134
|
+
Use `--status all` or `--status disabled` explicitly. Follow `page.next_cursor` with
|
|
135
|
+
`--cursor`; the cursor is bound to the query, category and status. No automatic full scan.
|
|
136
|
+
Category counts include both active and disabled tools. Only `catalog get` loads schemas.
|
|
137
|
+
Visibility is not permission to execute; server checks are authoritative.
|
|
138
|
+
|
|
139
|
+
Use `catalog get TOOL_KEY` directly when the public key is known. Search does not give
|
|
140
|
+
exact key matches a ranking bonus. A platform name such as `TikTok` can span many pages;
|
|
141
|
+
prefer a distinctive capability substring. For example, `视频生成` and `生成视频` are different
|
|
142
|
+
literal queries: rewrite the keyword or browse `--category video` after an empty result.
|
|
143
|
+
Do not concatenate keywords as if this were an AND or semantic query.
|
|
144
|
+
|
|
145
|
+
AI clients with shell access should use `agent-guide`: understand the user, choose short
|
|
146
|
+
keywords or a category, inspect a few candidates, fetch selected schemas, then call.
|
|
147
|
+
At most two keyword rewrites are suggested before browsing or clarifying the need.
|
|
148
|
+
The CLI does not make AI calls. Website search and its taxonomy remain separate.
|
|
149
|
+
|
|
150
|
+
`--input` accepts a JSON object, `@file.json`, or `@-` for UTF-8 stdin, at most 64 KiB.
|
|
151
|
+
Duplicate fields and non-finite numbers are rejected. Business validation happens on the
|
|
152
|
+
server. Prices reflect the current key's user pricing; a quote does not freeze charges.
|
|
153
|
+
|
|
154
|
+
## Recovery and task semantics
|
|
155
|
+
|
|
156
|
+
Each call creates an idempotency key and a non-secret local receipt **before** submitting.
|
|
157
|
+
Use `--idempotency-key KEY` to supply your own key. Receipts contain origin, tool, input
|
|
158
|
+
hash, creation time, idempotency key, and task ID when known; never the API key or input.
|
|
159
|
+
Location: `$MOUTER_STATE_DIR/receipts`, or the platform's user state directory. POSIX files
|
|
160
|
+
are created with mode 0600. There is no background cleanup or local task runner.
|
|
161
|
+
|
|
162
|
+
POST is never automatically retried. If `SUBMISSION_UNKNOWN` is returned, the server may
|
|
163
|
+
have accepted the task: retry with the **same key, credential authorization, tool and input within 24
|
|
164
|
+
hours**. The server rejects different input for the same key. After the window expires,
|
|
165
|
+
inspect the original task on the website rather than automatically starting another.
|
|
166
|
+
Local receipts also block accidental expired-key or different-input reuse. A missing
|
|
167
|
+
receipt does not extend the server's window; the caller must retain the original key/time.
|
|
168
|
+
|
|
169
|
+
HTTP requests have a 30-second operation budget with a 5-second connect timeout. GET may
|
|
170
|
+
retry twice within that budget and honors Retry-After. Waiting uses 1, 2, 4, then at most
|
|
171
|
+
5 seconds between polls, with small jitter. `--wait-timeout` defaults to 300 seconds and
|
|
172
|
+
bounds polling. Timeout or Ctrl+C stops the client only; **it does not cancel the task**.
|
|
173
|
+
Resume by task ID using the original credential authorization. OAuth token refresh keeps
|
|
174
|
+
the same authorization and receipt identity; logging in again creates a separate scope. Task reads are credential-scoped, so a
|
|
175
|
+
replacement key does not automatically grant access to old tasks.
|
|
176
|
+
|
|
177
|
+
`submitted`, `queued` and `in_progress` are nonterminal. `succeeded`, `failed`, `timed_out`
|
|
178
|
+
and `canceled` are terminal. A succeeded task with `result: null` has no currently available
|
|
179
|
+
result (for example because of retention); do not resubmit automatically.
|
|
180
|
+
|
|
181
|
+
## Output contract
|
|
182
|
+
|
|
183
|
+
Normal commands write one JSON document to stdout:
|
|
184
|
+
`code`, `message`, `data`, `request_id`, with optional `page` and `meta`.
|
|
185
|
+
Call metadata contains `idempotency_key`, `replayed`, and `receipt_saved`.
|
|
186
|
+
`--human` indents JSON, or prints the agent guide as text. JSON escapes control characters.
|
|
187
|
+
Help/version are normal terminal text. Prompts and nonessential diagnostics use stderr.
|
|
188
|
+
`--verbose` shows only method, public route, HTTP status and request ID, never raw
|
|
189
|
+
headers, credentials, request inputs, proxy responses or internal routing diagnostics.
|
|
190
|
+
|
|
191
|
+
| Exit | Meaning |
|
|
192
|
+
|---|---|
|
|
193
|
+
| 0 | Command succeeded (a submission can still be pending) |
|
|
194
|
+
| 1 | Unexpected client error |
|
|
195
|
+
| 2 | Invalid local arguments/input |
|
|
196
|
+
| 3 | Authentication, permission or credential-store error |
|
|
197
|
+
| 4 | Network, API or protocol error |
|
|
198
|
+
| 5 | A waited task failed, timed out on the server, or was canceled |
|
|
199
|
+
| 6 | Client wait deadline reached |
|
|
200
|
+
| 7 | Submission acceptance is unknown |
|
|
201
|
+
| 130 | Client interrupted |
|
|
202
|
+
|
|
203
|
+
`tasks get` exits 0 when it successfully reads a failed task; inspect `data.status`.
|
|
204
|
+
`tasks wait` and `call --wait` use exit 5 for an unsuccessful terminal task.
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["uv_build>=0.12,<0.13"]
|
|
3
|
+
build-backend = "uv_build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "mouter-cli"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Discover and call Mouter tools from a terminal or AI client"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.12"
|
|
11
|
+
dependencies = [
|
|
12
|
+
"httpx>=0.28,<1",
|
|
13
|
+
"simplejson>=3.19,<4",
|
|
14
|
+
]
|
|
15
|
+
|
|
16
|
+
[project.scripts]
|
|
17
|
+
mouter = "mouter_cli.cli:entrypoint"
|
|
18
|
+
|
|
19
|
+
[dependency-groups]
|
|
20
|
+
dev = [
|
|
21
|
+
"pytest>=8,<10",
|
|
22
|
+
"ruff>=0.12,<1",
|
|
23
|
+
"mypy>=1.10,<2",
|
|
24
|
+
"types-simplejson>=3.19,<4",
|
|
25
|
+
]
|
|
26
|
+
|
|
27
|
+
[tool.pytest.ini_options]
|
|
28
|
+
testpaths = ["tests"]
|
|
29
|
+
pythonpath = ["src"]
|
|
30
|
+
|
|
31
|
+
[tool.ruff]
|
|
32
|
+
line-length = 100
|
|
33
|
+
target-version = "py312"
|
|
34
|
+
|
|
35
|
+
[tool.ruff.lint]
|
|
36
|
+
select = [
|
|
37
|
+
"E",
|
|
38
|
+
"F",
|
|
39
|
+
"I",
|
|
40
|
+
"B",
|
|
41
|
+
"UP",
|
|
42
|
+
]
|
|
43
|
+
|
|
44
|
+
[tool.mypy]
|
|
45
|
+
python_version = "3.12"
|
|
46
|
+
strict = true
|
|
47
|
+
files = ["src"]
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["uv_build>=0.12,<0.13"]
|
|
3
|
+
build-backend = "uv_build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "mouter-cli"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Discover and call Mouter tools from a terminal or AI client"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.12"
|
|
11
|
+
dependencies = [
|
|
12
|
+
"httpx>=0.28,<1",
|
|
13
|
+
"simplejson>=3.19,<4",
|
|
14
|
+
]
|
|
15
|
+
|
|
16
|
+
[project.scripts]
|
|
17
|
+
mouter = "mouter_cli.cli:entrypoint"
|
|
18
|
+
|
|
19
|
+
[dependency-groups]
|
|
20
|
+
dev = [
|
|
21
|
+
"pytest>=8,<10",
|
|
22
|
+
"ruff>=0.12,<1",
|
|
23
|
+
"mypy>=1.10,<2",
|
|
24
|
+
"types-simplejson>=3.19,<4",
|
|
25
|
+
]
|
|
26
|
+
|
|
27
|
+
[tool.pytest.ini_options]
|
|
28
|
+
testpaths = ["tests"]
|
|
29
|
+
pythonpath = ["src"]
|
|
30
|
+
|
|
31
|
+
[tool.ruff]
|
|
32
|
+
line-length = 100
|
|
33
|
+
target-version = "py312"
|
|
34
|
+
[tool.ruff.lint]
|
|
35
|
+
select = ["E", "F", "I", "B", "UP"]
|
|
36
|
+
|
|
37
|
+
[tool.mypy]
|
|
38
|
+
python_version = "3.12"
|
|
39
|
+
strict = true
|
|
40
|
+
files = ["src"]
|