CLI

Get started with the CoCalc CLI

Install the CLI, sign in on your own computer, and inspect a project step by step.

Choose where you are running the CLI

On your own computer, install the CLI and sign in using the steps below. You need an existing CoCalc-ai account and a project that you can access.

Inside a CoCalc project or an agent session started by CoCalc, first try cocalc --version and cocalc auth status --check. Use the supplied project or agent authentication. Do not save a personal account login in a shared project. See authentication and targeting.

Step 1: Install on your own computer

For Linux (x64 or ARM64) or Apple Silicon macOS, open Terminal and run:

curl -fsSL https://software.cocalc.ai/software/cocalc/install.sh | bash

Follow the installer's printed PATH instruction if the command is not found. The standalone macOS installer currently supports Apple Silicon, not Intel Macs.

For native Windows x64, open PowerShell and run:

irm https://software.cocalc.ai/software/cocalc/install.ps1 -OutFile install-cocalc.ps1
.\install-cocalc.ps1 -AddToPath

Open a new terminal after adding the command to PATH. Then check:

cocalc --version
cocalc --help

The standalone download includes its runtime; you do not need to build the repository. The Unix installer defaults to the latest channel and Windows to stable. Available commands can therefore differ between installed releases. Use your installed command's help to check an option before relying on it.

Step 2: Read a page before signing in

These commands read documentation bundled with the CLI and need no login:

cocalc docs list --category CLI
cocalc docs show cli/use-cocalc-cli
cocalc docs search "project secrets"

Bundled documentation describes that CLI build. Updating the website does not update an already installed CLI.

Step 3: Sign in on your own computer

Create a named profile for this site:

cocalc --profile cocalc-ai --api https://cocalc.ai auth login

Leave the command running. Open the approval URL printed in your terminal, sign in to the intended account, and approve the CLI login. Return to the terminal and wait for completion. The CLI saves the profile and makes it current.

Check the saved profile:

cocalc --profile cocalc-ai --json auth status --check

Confirm data.selected_profile, the account identity, and data.check.ok: true. The outer ok: true only means the status command returned a result. Without --check, the command describes configuration without testing the connection.

Login may save your account's routed site address. Continue using the profile without repeating --api on every command.

Step 4: Find and inspect a project

cocalc --profile cocalc-ai project list

Copy the full project_id for the project you intend to use. Replace PROJECT_ID in these commands with that value:

cocalc --profile cocalc-ai project get --project PROJECT_ID
cocalc --profile cocalc-ai project file list --project PROJECT_ID .

Confirm the project ID and title before doing further work. A successful listing is your first project operation; an empty project can return an empty list. A full ID avoids ambiguous project names.

To save this project as the default for the current local directory:

cocalc --profile cocalc-ai project use --project PROJECT_ID
cocalc --profile cocalc-ai project get

This creates .cocalc-project in that directory. It does not save credentials. Use explicit --project arguments in scripts that may run from other directories.

Next steps