Manage workspaces and notices with the CLI

Organize a directory inside a project

A workspace is a saved organizational record for a project directory. Creating one does not create a project, clone a repository, or start an agent. Workspace records are scoped to the selected project and account.

Use Bash variables CLI_PROFILE and PROJECT_ID as in the quickstart. Set WORKSPACE_ROOT to an absolute path inside the project, not a path on your own computer:

export CLI_PROFILE=cocalc-ai
export PROJECT_ID='REPLACE_WITH_FULL_PROJECT_ID'
export WORKSPACE_ROOT='/home/user/research'

cocalc --profile "$CLI_PROFILE" project get --project "$PROJECT_ID"
cocalc --profile "$CLI_PROFILE" --json workspaces list \
  --project "$PROJECT_ID"

Step 1: Create only when the root has no workspace

If the list already contains that root, retain its workspace ID and update the existing record. Repeating create for the same root replaces its saved metadata. For a new workspace:

cocalc --profile "$CLI_PROFILE" --json workspaces create "$WORKSPACE_ROOT" \
  --project "$PROJECT_ID" --title "Research" \
  --description "Analysis and project notes" --pinned true

Retain data.workspace_id as WORKSPACE_ID. Confirm project_id, root_path, title, and pinned state. Creating this record does not create or verify the underlying directory.

Step 2: Update and resolve

export WORKSPACE_ID='REPLACE_WITH_RETURNED_WORKSPACE_ID'

cocalc --profile "$CLI_PROFILE" --json workspaces update "$WORKSPACE_ID" \
  --project "$PROJECT_ID" --title "Research review"
cocalc --profile "$CLI_PROFILE" --json workspaces resolve "$WORKSPACE_ROOT" \
  --project "$PROJECT_ID"

Updates preserve unspecified fields. resolve returns the most specific workspace matching the path, or data:null. It does not check whether the path exists. Selecting a workspace in a browser is separate from editing this persistent record.

Step 3: Leave a durable message

cocalc --profile "$CLI_PROFILE" --json workspaces message "$WORKSPACE_ID" \
  --project "$PROJECT_ID" "The analysis is ready for review."

Check data.result.ok:true. Retain data.result.message_id and data.result.chat_path. The command creates or reuses the workspace's canonical chat and its “Workspace notices” thread.

A workspace message does not submit an agent prompt or start an agent turn. It records a notice for collaborators. Use the relevant agent workflow when the intent is to execute work.

After verifying a browser target, open the chat separately with its browser ID:

cocalc --profile "$CLI_PROFILE" --json workspaces open-chat "$WORKSPACE_ID" \
  --project "$PROJECT_ID" --browser "$BROWSER_ID"

With message --open, the message is saved before the browser is opened. A browser-opening failure does not prove that the message was unsaved. Inspect the chat before retrying to avoid duplicate notices.

Card notices and cleanup

A card notice is distinct from a chat message:

cocalc --profile "$CLI_PROFILE" --json workspaces notify "$WORKSPACE_ID" \
  --project "$PROJECT_ID" --level success "Ready for review."
cocalc --profile "$CLI_PROFILE" --json workspaces clear-notice "$WORKSPACE_ID" \
  --project "$PROJECT_ID"
cocalc --profile "$CLI_PROFILE" --json workspaces update "$WORKSPACE_ID" \
  --project "$PROJECT_ID" --pinned false

These operations do not start an agent. To remove the organizational record:

cocalc --profile "$CLI_PROFILE" --json workspaces delete "$WORKSPACE_ID" \
  --project "$PROJECT_ID"

Check data.deleted:true. Project files and the chat file remain intact.