Install the CLI
Install the CosmicAC CLI and point it at your deployment.
Install the CosmicAC CLI and point it at your deployment to create and manage jobs from your terminal.
Prerequisites
You need the following before you start:
- Node.js 20 or later.
- npm.
- A GitHub personal access token (PAT) with the
read:packagesscope. - A running CosmicAC deployment. See Installation to deploy CosmicAC.
If you don't have a PAT, see Create a GitHub PAT with the read:packages scope. The CosmicAC CLI is a private package hosted on GitHub Packages and not the npm registry.
If you use Socket Firewall, see Configure custom registries for Socket Firewall. Socket Firewall allows only the registries that it's configured with, so the installation fails until you allow GitHub Packages.
Steps
Install the CLI
Configure npm to use the GitHub Packages registry for the @tetherto scope, then install the CLI globally:
npm config set @tetherto:registry https://npm.pkg.github.com
npm install -g @tetherto/cosmicac-cliConfirm the CLI runs:
cosmicac --helpIf the CLI lists the available commands, the installation succeeded. See CLI commands for the full reference.
Point the CLI at your deployment
Set the URLs for a named environment. Replace https://cosmicac.example.com with your Base URL, and keep the /api and /inference paths:
cosmicac config set --env production \
--app-url https://cosmicac.example.com/api \
--inference-url https://cosmicac.example.com/inference \
--web-url https://cosmicac.example.comThe Base URL is the address where your CosmicAC UI is reachable. It can be localhost, a server IP, or a domain name.
A new environment needs all three URLs. To point the CLI at another deployment, run the same command with a different --env name.
Confirm the configuration
Check that the CLI points at your deployment:
cosmicac config showThe output shows the active environment and its URLs. They should match your deployment.
Help and troubleshooting
Create a GitHub PAT with the read:packages scope
- Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic).
- Click Generate new token (classic).
- Give it a descriptive name, for example
CosmicAC CLI. - Select the
read:packagesscope. - Click Generate token and copy it immediately, because you won't see it again.
- Run this command, replacing
{YOUR_PAT_HERE}with your token:
npm config set //npm.pkg.github.com/:_authToken {YOUR_PAT_HERE}Learn more about creating a personal access token.
Configure custom registries for Socket Firewall
Socket Firewall allows only the registries it's configured with, so npm install fails with a 403 error and can't reach GitHub Packages. The error names npm.pkg.github.com as the blocked hostname.
To allow GitHub Packages, add this line to .sfw.config in your home directory:
SFW_CUSTOM_REGISTRIES=npm:npm.pkg.github.comOn macOS and Linux, the file is ~/.sfw.config. On Windows, it's %USERPROFILE%\.sfw.config. Create the file if it doesn't exist.
Install the CLI again:
npm install -g @tetherto/cosmicac-cliIf the 403 doesn't mention a blocked hostname, Socket Firewall isn't the cause. npm reached GitHub Packages and it rejected your credentials, so check your GitHub PAT.