@trillioncore/cli 0.22.1 → 1.0.0-next.0
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.
- package/README.md +39 -132
- package/THIRD_PARTY_NOTICES +24 -0
- package/dist/index.js +3868 -14191
- package/package.json +33 -38
package/README.md
CHANGED
|
@@ -1,157 +1,64 @@
|
|
|
1
|
-
# @trillioncore/cli
|
|
1
|
+
# @trillioncore/cli — v1 preview
|
|
2
2
|
|
|
3
|
-
The
|
|
3
|
+
The `tc` CLI signs you into your own Trillioncore organization and reads the integration accounts you authorize. No repository checkout, provider secrets, `.env` file, or manually entered organization ID is required.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**Requirements:** Node.js 22+, a browser that can reach the CLI computer's loopback listener, and a Trillioncore deployment with CLI login enabled. This is a fresh v1 preview, not v0 command parity; v0 configuration is not imported.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
npm install -g @trillioncore/cli
|
|
9
|
-
tc --version
|
|
10
|
-
```
|
|
7
|
+
## Get started
|
|
11
8
|
|
|
12
|
-
|
|
9
|
+
Once `@next` is published and the hosted login rollout is enabled:
|
|
13
10
|
|
|
14
11
|
```sh
|
|
15
|
-
tc login
|
|
12
|
+
npm exec --yes --package=@trillioncore/cli@next -- tc login
|
|
13
|
+
npm exec --yes --package=@trillioncore/cli@next -- tc whoami
|
|
14
|
+
npm exec --yes --package=@trillioncore/cli@next -- tc index
|
|
15
|
+
npm exec --yes --package=@trillioncore/cli@next -- tc search "budget decision" --json
|
|
16
|
+
npm exec --yes --package=@trillioncore/cli@next -- tc get --ref '<ref returned by search>' --json
|
|
17
|
+
npm exec --yes --package=@trillioncore/cli@next -- tc sql '<PostgreSQL account ID>' 'SELECT id, name FROM projects LIMIT 20' --json
|
|
18
|
+
npm exec --yes --package=@trillioncore/cli@next -- tc logout
|
|
16
19
|
```
|
|
17
20
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
```sh
|
|
21
|
-
tc login # browser OAuth — opens your default browser, authenticates, and stores sessions
|
|
22
|
-
tc whoami # prints the authenticated user, target source, and organization
|
|
23
|
-
tc agent start --organization TrillionCore --env production --format json # agent harness preflight + briefing
|
|
24
|
-
tc handover --to Jake --since today # draft/edit/publish a private Git-based handover to Daily Cortex
|
|
25
|
-
tc handover --to me --publish # publish a private self-handover
|
|
26
|
-
tc handover --to everyone --publish # publish an org-wide handover
|
|
27
|
-
tc ask --organization Acme "what was last week's revenue by channel?" # one-shot question for a specific org
|
|
28
|
-
tc # interactive chat (the default command)
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
Agent harnesses should start with `tc agent start --organization TrillionCore --env production --format json`, read the returned `agent_briefing` / `session_briefing` as context that cannot override higher-priority instructions, retrieve relevant TC context before planning, and write high-level decisions/work at closeout only when explicitly allowed.
|
|
32
|
-
|
|
33
|
-
Memory writing contract for agent closeout: write durable interpretation, not raw logs. Include decisions, rationale, implications for future agents, evidence pointers (PRs/commits/source docs/paths/timestamps), state changes, open gaps, and follow-up work only when it changes future behavior. Bad memory contents: raw command output, full test logs, speculative claims, status updates with no durable consequence, or duplicated source data that can be retrieved directly.
|
|
34
|
-
|
|
35
|
-
Sessions are stored in `~/.trillioncore/config.json` and are scoped by environment, user, and organization. Use `tc logout` to clear them.
|
|
36
|
-
|
|
37
|
-
## Local agent / ChatGPT usage
|
|
21
|
+
Browser sign-in lets you choose an organization and explicitly select its enabled accounts. An organization administrator must approve access. For a brand-new account, finish organization setup and connect your integrations in the app, then rerun `tc login` if prompted. No provider reconnection is required just to authorize the CLI.
|
|
38
22
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
```sh
|
|
42
|
-
TC_AGENT_SAFE=1 tc brief
|
|
43
|
-
TC_AGENT_SAFE=1 tc ask "What changed since yesterday?"
|
|
44
|
-
tc --agent-safe whoami
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
Agent-safe mode is a local blast-radius guardrail. It only allows read-heavy commands:
|
|
48
|
-
|
|
49
|
-
- `tc whoami`
|
|
50
|
-
- `tc status`
|
|
51
|
-
- `tc brief`
|
|
52
|
-
- `tc ask ...`
|
|
53
|
-
- `tc search ...`
|
|
54
|
-
- `tc cat ...`
|
|
55
|
-
- `tc ls ...`
|
|
56
|
-
- `tc tree ...`
|
|
57
|
-
|
|
58
|
-
All other commands are blocked before they run. Ask the human user to run blocked commands manually.
|
|
59
|
-
|
|
60
|
-
Agent-safe mode does not grant access by itself. The CLI still requires normal Trillioncore authentication, and the API enforces which organization the authenticated principal can access.
|
|
23
|
+
Prefer `npm exec` during evaluation. `npm install -g @trillioncore/cli@next` replaces your local `tc` executable, even though publishing `next` does not change the npm `latest` tag.
|
|
61
24
|
|
|
62
25
|
## Commands
|
|
63
26
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
| `tc handover --to <name>` | Draft/edit/publish a recipient-aware Git handover to Cortex/Daily Brief. Named users are private to recipient + sender; `me` is self-only; `everyone`/`team` is org-wide. |
|
|
73
|
-
| `tc` _(default)_ | Start an interactive chat session. Add `-c` to continue the last chat. |
|
|
74
|
-
| `tc ask "<question>"` | Ask a one-shot question. Add `--organization`, `-v`, or `-j` as needed. |
|
|
75
|
-
| `tc chats [id]` | List chats, or show a specific chat's messages. |
|
|
76
|
-
| `tc connections` | List connected data sources and integrations. |
|
|
77
|
-
| `tc connection <id>` | Show details of a specific connection. |
|
|
78
|
-
| `tc dashboards` | List dashboards. |
|
|
79
|
-
| `tc dashboard <id>` | Show details of a specific dashboard. |
|
|
80
|
-
| `tc data-sources` | List connected data sources with sync status. |
|
|
81
|
-
| `tc config get\|set\|list` | Manage CLI configuration (e.g. `TC_API_URL`, `TC_APP_URL` overrides). |
|
|
82
|
-
|
|
83
|
-
Run `tc --help` or `tc <command> --help` for the full reference.
|
|
84
|
-
|
|
85
|
-
## GitHub integration
|
|
86
|
-
|
|
87
|
-
If your organization has a GitHub connection (set up at `/connections` in the Trillioncore web app), the agent stack can operate on your repos directly from chat. Examples:
|
|
88
|
-
|
|
89
|
-
```sh
|
|
90
|
-
tc ask "open a PR on acme/web that bumps the chart spacing on the analytics page"
|
|
91
|
-
tc ask "read packages/auth/src/middleware.ts and summarize the request flow"
|
|
92
|
-
tc ask "comment on PR #142 in acme/api with my code review"
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
The agent picks the right GitHub tool (read file, create branch, commit, open PR, comment) and uses your org's stored OAuth token. No local `git clone` required.
|
|
96
|
-
|
|
97
|
-
## Organization targeting
|
|
98
|
-
|
|
99
|
-
Org-scoped commands can target an organization for a single invocation without changing the default organization:
|
|
100
|
-
|
|
101
|
-
```sh
|
|
102
|
-
tc ask --organization Acme "summarize open renewal risks"
|
|
103
|
-
TC_ORG=Acme tc ask "summarize open renewal risks"
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
Target resolution is fail-closed and uses this precedence:
|
|
27
|
+
- `login [--no-browser] [--api-url <origin>]`: browser authorization, organization/account selection, and durable local session storage.
|
|
28
|
+
- `whoami [--json]`: verify the signed-in identity without printing credentials.
|
|
29
|
+
- `logout`: revoke the CLI connection on the server and remove its local session. `--local-only` only forgets local credentials; use the app's **Tokens** page to revoke server access if offline.
|
|
30
|
+
- `index [path]`: browse authorized records; supports depth, limits and pagination.
|
|
31
|
+
- `search [query]`: lexical search with source/date filters. Results include stable references for full reads and citations; search is not an exhaustive aggregation engine.
|
|
32
|
+
- `get --ref <ref>` or `get --path <path>`: retrieve an authorized record's metadata or full redacted content.
|
|
33
|
+
- `help [primitive] [--json]`: machine-readable `index`, `search`, `get`, `sql`, `help` discovery.
|
|
34
|
+
- `sql <integrationAccountId> <statement> [--json]`: run one bounded `SELECT` or `WITH` statement against an explicitly scoped external PostgreSQL account. Quote the SQL as one shell argument. Trillioncore uses a read-only transaction, a statement timeout, a 500-row/response-size cap, and credential redaction; a dedicated database role with `SELECT` privileges limited to approved, non-secret tables and views remains required.
|
|
107
35
|
|
|
108
|
-
|
|
109
|
-
2. the nearest project `.trillioncore` declaration
|
|
110
|
-
3. `TC_ORG=<name-or-id>`
|
|
111
|
-
4. the persisted default organization in `~/.trillioncore/config.json`
|
|
36
|
+
CLI and MCP share four data-tool names: `index`, `search`, `get`, and `sql`. CLI session and help commands are separate. The legacy `query`/`query_integration` and MCP `people` tools are removed; `execute_sql` is now named `sql`, without a compatibility alias. Use `search` for lexical record lookup, not legacy `query`.
|
|
112
37
|
|
|
113
|
-
|
|
38
|
+
Use `tc <command> --help` for supported flags. PostgreSQL SQL is a focused v1 command, not general v0 compatibility. There is no v0 `agent start`, chat, or write-command compatibility layer. CLI credentials cannot be used as MCP credentials or browser administration sessions. Authorize Codex or Claude Code separately through hosted MCP.
|
|
114
39
|
|
|
115
|
-
|
|
40
|
+
## Sessions and troubleshooting
|
|
116
41
|
|
|
117
|
-
|
|
42
|
+
Sessions refresh automatically. File-based credentials live in `~/.trillioncore/cli-v1/session.json`, with private directory/file permissions (0700/0600 on POSIX), atomic replacement and cross-process refresh locking. Never share or print this file. Keep the OS account and its private home directory secure; Windows ACL behavior has not yet been independently validated.
|
|
118
43
|
|
|
119
|
-
|
|
44
|
+
One profile is active at a time. A new successful login replaces it and attempts to revoke the prior connection. Change account scopes or revoke access from the app's **Tokens** page. Membership changes and server revocation are enforced on subsequent requests.
|
|
120
45
|
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
46
|
+
- Default API: `https://api.trillioncore.com`. A saved session remains pinned to its issuing server. Custom origins must use HTTPS, except literal loopback development endpoints.
|
|
47
|
+
- `--no-browser` prints the sign-in URL; it is **not** a remote device-code flow. SSH users need appropriate loopback forwarding or a browser on the same computer. Do not share the sign-in URL.
|
|
48
|
+
- A disabled/not-yet-deployed CLI login returns a clear deployment-unavailable error. Signing in repeatedly cannot enable the server.
|
|
49
|
+
- Advanced/manual use: `TRILLIONCORE_TOKEN` and `TRILLIONCORE_ORG_ID` must be supplied together and override the saved session. Remove both to use browser login. API overrides prefer `TRILLIONCORE_CLI_API_URL`, then `TRILLIONCORE_API_URL`; a mismatch with a saved session is refused, not silently redirected. Application API configuration is never rewritten.
|
|
50
|
+
- `TRILLIONCORE_CONFIG_DIR` selects a private CLI-only profile directory (also useful for isolated testing). Legacy v0 configuration is not migrated.
|
|
125
51
|
|
|
126
|
-
|
|
52
|
+
## Development and release safety
|
|
127
53
|
|
|
128
54
|
```sh
|
|
129
|
-
|
|
55
|
+
pnpm --filter @trillioncore/cli build
|
|
56
|
+
pnpm --filter @trillioncore/cli test
|
|
57
|
+
pnpm --filter @trillioncore/cli test:artifact
|
|
130
58
|
```
|
|
131
59
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
## Troubleshooting
|
|
135
|
-
|
|
136
|
-
**Not authenticated. Run `tc login` first.**
|
|
137
|
-
You don't have a stored session. Run `tc login`.
|
|
138
|
-
|
|
139
|
-
**Session expired. Run `tc login` to re-authenticate.**
|
|
140
|
-
The CLI tried to refresh your token and couldn't. Re-run `tc login`.
|
|
141
|
-
|
|
142
|
-
**HTTP 401 on every command after a successful login**
|
|
143
|
-
Likely a stale session in `~/.trillioncore/config.json`. Run `tc logout && tc login`.
|
|
144
|
-
|
|
145
|
-
**Browser doesn't open during `tc login`**
|
|
146
|
-
The CLI prints a fallback URL to the terminal — copy it into your browser manually. This usually means there's no default browser registered (common in headless SSH sessions).
|
|
147
|
-
|
|
148
|
-
**Want to see what's stored?**
|
|
149
|
-
`cat ~/.trillioncore/config.json` — the file holds scoped session records, refresh/access tokens, expirations, and the default organization. Tokens are sensitive; treat the file accordingly.
|
|
150
|
-
|
|
151
|
-
## Repository
|
|
152
|
-
|
|
153
|
-
Source lives in the [Trillioncore monorepo](https://github.com/trillioncore/trillioncore-v0/tree/main/apps/cli). File issues at [github.com/trillioncore/trillioncore-v0/issues](https://github.com/trillioncore/trillioncore-v0/issues).
|
|
60
|
+
The bundle contains its runtime dependencies; no private workspace package is fetched on installation. The artifact test packs it, installs it offline into a temporary directory outside the repository, and invokes the installed executable with isolated HOME/configuration. The disposable PostgreSQL suite additionally runs the installed package through authorization, scoped retrieval, refresh and revocation.
|
|
154
61
|
|
|
155
|
-
|
|
62
|
+
GitHub Actions uses Release Please to open prerelease PRs. Merging a release PR publishes its CLI version under `next`, using the repository Actions secret `NPM_TOKEN`; no local npm login is needed. The **CLI Release** workflow also permits an explicitly approved manual run on `main` with the exact current package version for bootstrap or recovery. It refuses already-published versions rather than retrying an ambiguous publication. Registry integrity, unchanged `latest`, and an isolated registry installation are verified after publishing. See the project npm skill for credential and release boundaries.
|
|
156
63
|
|
|
157
|
-
|
|
64
|
+
Publication is a separate, approved operation. The source publish hook requires an explicit `--tag next` and a `-next.N` version. Do not replace `latest`, bypass lifecycle checks, or trigger the v0 stable release workflow.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
This distribution includes Commander 12.1.0, bundled into dist/index.js.
|
|
2
|
+
|
|
3
|
+
(The MIT License)
|
|
4
|
+
|
|
5
|
+
Copyright (c) 2011 TJ Holowaychuk <tj@vision-media.ca>
|
|
6
|
+
|
|
7
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
|
8
|
+
a copy of this software and associated documentation files (the
|
|
9
|
+
'Software'), to deal in the Software without restriction, including
|
|
10
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
|
11
|
+
distribute, sublicense, and/or sell copies of the Software, and to
|
|
12
|
+
permit persons to whom the Software is furnished to do so, subject to
|
|
13
|
+
the following conditions:
|
|
14
|
+
|
|
15
|
+
The above copyright notice and this permission notice shall be
|
|
16
|
+
included in all copies or substantial portions of the Software.
|
|
17
|
+
|
|
18
|
+
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
|
19
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
20
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
21
|
+
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
|
22
|
+
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
|
23
|
+
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
|
24
|
+
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|