Part 1: Setting a Project (CLI)

Introduction

If you are building a pricing engine, a research pipeline, or a dashboard, the bottleneck is usually infrastructure: repositories, environments, storage, compute, permissions, and deployment.

Main Sequence removes that setup overhead. A project gives you a production-ready workspace where code, data, and compute are already connected.

The Main Sequence platform allows you to:

1. rapidly build and deploy data products and data workflows as a unified API with a normalized structure through DataNodes
2. rapidly deploy RBAC-enabled dashboards on the platform
3. rapidly deploy agents using the Google Agent SDK

The key idea is that you can focus on development and deployment, while the platform handles the DevOps layer.

This chapter uses a CLI-only flow.

Quick Summary

In this part, you will:

• create a new project from the CLI
• map the project to your local machine
• open the project folder and build the local Python environment
• learn the default project parameters used by the platform

DataNodes created in this part: none.

This tutorial is intentionally CLI-only.

Some of the setup steps can also be done through the VS Code extension, but that flow is kept separate. A dedicated GUI tutorial will live under docs/tutorial_gui/.

1. Install and Verify the CLI

Open a terminal and install:

pip install mainsequence

Then verify:

mainsequence --help
# or:
python -m mainsequence --help

2. Log In

mainsequence login

You can validate access with:

mainsequence project list

3. Search Existing Projects

Before you create a new project, search for likely existing projects that may already use a similar name:

mainsequence project search "tutorial"

This command performs fuzzy search over the projects visible to your current user. It requires at least 3 query characters, returns up to 20 matches by default, and shows the project id, project name, repository branch, and cluster id for each result.

Use it to quickly check whether a tutorial name such as tutorial-project-cli or a similar variation is already in use. If you need more than the default result count, add --limit.

You can also validate the exact candidate name directly:

mainsequence project validate-name "tutorial-project-cli"

This command is the exact create-time availability check. It confirms whether the name is available, shows the normalized slug/library names the platform will derive from it, and prints suggested alternatives when the name is already taken.

4. Create a New Project

Run:

mainsequence project create [PROJECT_NAME]

Example:

mainsequence project create tutorial-project-cli

The CLI validates the project name before continuing, prompts for any missing values, and uses sensible defaults. It also polls the backend every 30 seconds until is_initialized=true.

5. Confirm Project Creation

List projects and identify the new project ID:

mainsequence project list

You should see your new project with an ID, for example:

ID   Project               Data Source  Class         Status     Local  Path
--   -------               -----------  -----         ------     -----  ----
130  tutorial-project-cli  Default DB   timescale_db  AVAILABLE  -      -

6. Set Up the Project Locally

Use the project ID from the previous step:

mainsequence project set-up-locally [PROJECT_ID]

Example:

mainsequence project set-up-locally 130

Verify mapping:

mainsequence project list

The Local column should show Local, and Path should point to your local folder.

7. Open a Signed Terminal (Required for Git Push/Pull)

Before running git commands, open a signed terminal so the project SSH key is loaded in ssh-agent.

macOS/Linux (bash/zsh)

mainsequence project open-signed-terminal 130

Windows (PowerShell)

mainsequence project open-signed-terminal 130

Use the newly opened terminal for git pull, git push, and any other git operations against the project repository.

8. Move Into the Project You Just Created

macOS/Linux (bash/zsh)

PROJECT_ID=130
PROJECT_PATH=$(mainsequence project list | awk -v id="$PROJECT_ID" '$1 == id {print $NF}')
cd "$PROJECT_PATH"
pwd

Windows (PowerShell)

$ProjectId = 130
$ProjectPath = (
  mainsequence project list |
  Select-String "^\s*$ProjectId\s+" |
  ForEach-Object { ($_ -split '\s{2,}')[-1] }
)
Set-Location $ProjectPath
Get-Location

If open-signed-terminal opened directly in the project folder, you can keep working there and skip this step.

9. Understand the Folder Structure Created

After mainsequence project set-up-locally [PROJECT_ID], your local project folder should look similar to:

tutorial-project-cli-130/
├── .env
├── pyproject.toml
├── requirements.txt
├── src/
├── dashboards/
├── tests/
├── Dockerfile          (if DEFAULT_BASE_IMAGE is available)
└── .dockerignore       (if DEFAULT_BASE_IMAGE is available)

Key points: - .env is generated by the CLI during local setup and includes project runtime variables (for example MAINSEQUENCE_ACCESS_TOKEN, MAINSEQUENCE_REFRESH_TOKEN, MAINSEQUENCE_ENDPOINT, and MAIN_SEQUENCE_PROJECT_ID). - src/, dashboards/, tests/, pyproject.toml, and requirements.txt come from the project repository scaffold. - Dockerfile and .dockerignore are scaffolded only when a default base image is present.

10. Build the Local Environment

Inside the project folder, create and sync a local .venv:

mainsequence project build_local_venv --path .

This command: - reads pyproject.toml, - creates .venv with the requested Python version, - runs uv sync into that .venv.

After this step, your folder will also include:

tutorial-project-cli-130/
└── .venv/

After completion, your project is ready for local development.

For a deeper reference on the CLI workflow behind this setup, see CLI Deep Dive.