Repository navigation
Publishing the PK CLI for General Use #268
Description
Activity
Review CLI exit codes in relation to sysexit standards
Exceptions are currently using sysexit codes from this stanard: https://www.freebsd.org/cgi/man.cgi?query=sysexits&apropos=0&sektion=0&manpath=FreeBSD+4.3-RELEASE&format=html
It's a good idea to review these exit codes and see how to ensure we all of our CLI commands are returning the proper exit codes.
Bundling and Minification Step in our Release Executables
Recommend attempting the usage of a minifier before we package it up using pkg. Right now tsc doesn't minify the JS code nor does it do any optimisations.
Here's some resources:
- http://typescript-react-primer.loyc.net/minification.html
- https://github.com/privatenumber/minification-benchmarks
- https://github.com/vercel/ncc - this is by the same people using vercel/pkg, the
nccwould be used first to take ourdistinto a single file, so I'm not sure what happens to ourjsondata, and thenpkgcan run against the single file
Basically, right now
tscproduces thedist. We would want to pass thedistinto a minifier/bundler likeesbuildorterserorncc, and then pass the final single file result topkg.Ideally the "bundling" step should also perform optimisations like DCE.
This should reduce the size of the final executable by a significant amount, possibly 70%, and it should also help with the performance of the code as in #277 since it won't need to load different files.
However for
npmpublishing, it will still usedistas normal unminified and all. This makes it useful for libraries. This bundling step would only be done temporarily within our release builds to executables. It does not apply toapplicationnordockertarget.Should review the CLI error handling overall, see this thread: #278 (comment) and https://github.com/MatrixAI/js-polykey/wiki/API-Design
Noticed that sometimes we need our
--verbosemessaging because by default onlyWARNmessages are shown. Now some message are useful for the user. Some messages are useful for the debugger/developer. So we may need to raise our message levels internally toDEBUG. That way info messages useful to the user can still be shown. On the other hand, I'm not sure if I like this as well.Perhaps instead we need another level, or level of messages that is given interactively. That is one could say that messages intended for interactive usage can be
this.logger.warn.Alternatively, interactive messages may need to go directly to
process.stderr.writerather than using the logger even though the logger does use STDERR.Not entirely sure atm. Because this has to interact with formatting and error handling too.
Pkg seems quite limited:
We need to see if alternatives are better.
Related issues:
@tegefaulkes this is our epic for PK CLI. We can attach issues related to it here.
Also all of the issues relating CLI stuff will get moved to Polykey-CLI.
First we factor out, then we move issues.
K. I can split out the CLI soon. There are a lot of pending changes in the agent migration PR, so doing them side by side is not ideal. I can get the agent migration to a working state and merge that, some of the remaining tasks for that can be a 2nd PR.
So I can merge #525, then split out the CLI, and complete the remainder of the migration. The remaining part should be consolidating the quic server and reverse connection handling into the node connection manager.
Moving to Polykey-CLI.
I'd say this is done... sort of. There's nothing more to do for this issue, but just massaging Polykey-CLI to be better.
More specific issues can be created for integrating a bundler, compression, and maybe even replacing
pkgwith our own creation.Reopening this right now, cause there are few subissues to solve here as part of 6th testnet deployment.
Now that things are built and PK CLI master and staging is synced, this is done.
- added a parent issue
on Oct 23, 2025
Requirements of this design
The new structure of our projects is:
Polykey
Polykey-CLI
Polykey-Desktop - electron/tauri wrapper around library code
Polykey-Mobile - nativescript wrapper around library code
We may not need to split out to Polykey-CLI just yet, but it can be done later.
Additional context
Specification
polykey, as Polykey Core library now usespolykeypolykey@matrixai/polykeyand make it point topolykeyand make the deprecatedjs-polykeyand make it point topolykey