Install the CLI
Install the CosmicAC CLI, set the URLs for your deployment, and sign in.
Install the CosmicAC CLI, set the URLs for your deployment, and sign in, so that you can create and manage jobs from your terminal.
Prerequisites
Before you start, make sure that you have the following.
- Node.js 18 or later.
- npm.
- A GitHub personal access token (PAT) with the
read:packagesscope. - A running CosmicAC deployment. See Set up CosmicAC.
The CosmicAC CLI is a private package on GitHub Packages, not on the npm registry. If you don't have a PAT, see Create a GitHub PAT with the read:packages scope.
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, and then install the CLI globally.
npm config set @tetherto:registry https://npm.pkg.github.com
npm install -g @tetherto/cosmicac-cliCheck that the CLI runs.
cosmicac --helpIf the CLI lists the available commands, the installation succeeded. For every command, see CLI commands.
Set the URLs for your deployment
Set the URLs for a named environment. Replace <base-url> with your CosmicAC base URL, and keep the /api and /inference paths.
cosmicac config set --env production \
--app-url <base-url>/api \
--inference-url <base-url>/inference \
--web-url <base-url>The base URL is the address of your CosmicAC web interface, such as localhost, a server IP address, or a domain name.
A new environment needs all three URLs. To set up another deployment, run the same command with a different --env name.
Sign in
If your deployment has authentication turned on, sign in.
cosmicac loginThe CLI opens the CosmicAC web interface in your browser. Approve the request within 5 minutes.
If no browser is available, for example over SSH, print the sign-in URL instead, and then open it on another machine.
cosmicac login --no-browserAfter you sign in, the CLI selects a team and prints its name. To use another team, list your teams, and then select one by its ID or name.
cosmicac teams list
cosmicac teams use <team>Confirm the configuration
Check the active environment.
cosmicac config showThe output shows the active environment, its URLs, and its TEAM_ID. The URLs should match your deployment.
If you signed in, check your user and teams.
cosmicac whoamiHelp and troubleshooting
Create a GitHub PAT with the read:packages scope
- In GitHub, go to Settings > Developer settings > Personal access tokens > Tokens (classic).
- Click Generate new token (classic).
- Enter a descriptive name, such as
CosmicAC CLI. - Select the
read:packagesscope. - Click Generate token, and copy the token. GitHub shows it only once.
- Save the token to your npm configuration. Replace
<your-pat>with your token.
npm config set //npm.pkg.github.com/:_authToken <your-pat>For more information, see Managing your personal access tokens.
Configure custom registries for Socket Firewall
Socket Firewall allows only the registries that 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 the following 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 error doesn't name a blocked hostname, Socket Firewall isn't the cause. npm reached GitHub Packages, and GitHub Packages rejected your credentials, so check your GitHub PAT.
Commands fail with "Not signed in, or the stored session expired."
Your deployment has authentication turned on, and the CLI has no valid session for the active environment. Sign in again.
cosmicac loginApproval fails in the browser with "teamId is required"
The web interface doesn't name a team when it approves a CLI sign-in. For an account that belongs to two or more teams, CosmicAC rejects the approval with this error.