Meridian documentation
Everything you need to run your team in Meridian. For the API and MCP server, see the API reference.
Getting started
Sign up to create a workspace and its first team. A team owns issues, a workflow (its statuses), labels and cycles. Invite teammates from Settings → Members : with email set up they get a link by email, otherwise you copy the link.
Press C anywhere to create an issue, ⌘K to open the command menu, and ? to see every shortcut.
Issues
Issues have a status, priority, assignee, labels, estimate, start and due dates, a project and milestone, and a cycle. Paste images into the description, use - [ ] for checklists and @name to mention someone.
- Sub-issues : open an issue and choose Add sub-issue.
- Relations : blocks, blocked by, related, duplicate. Marking a duplicate cancels the issue.
- Templates : save any issue as a template, or create them in Settings → Templates.
- Recurring issues : issue menu → Repeat.
- Archive with
#, trash with⌘⌫, and restore from Settings → Archive & trash.
Lists, boards and views
Every issue list can be shown as a list or a board, grouped by status, assignee, priority, project, cycle, label, team or milestone, and filtered on any field. Choose Save as view to keep it.
On a board grouped by status, columns are the team's statuses : add one with Add column, double-click a title to rename it, drag the handle to reorder, and use the column menu to recolor, change its category, hide it, or delete it (you pick where its issues go). Grouped by label or project, the same menu manages labels or projects.
Keyboard shortcuts
C | Create issue |
⌘K | Command menu |
J / K | Move down / up |
X | Select |
Space | Peek |
Enter | Open |
S / P / A / L / E | Status, priority, assignee, labels, estimate |
⇧P / ⇧C / ⇧D / ⇧M / ⇧T | Project, cycle, due date, milestone, team |
I | Assign to me |
F | Favorite |
G then I / M / P / V / S | Inbox, my issues, projects, views, settings |
⌘Z | Undo |
Cycles and triage
Turn on cycles in team settings and pick the length, cooldown and start day. Meridian keeps the next cycles created, closes ended ones and moves unfinished issues forward. Each cycle shows a burn-up chart.
With triage on, issues from guests and integrations land in Triage, where someone accepts, declines or merges them as duplicates.
Projects, Gantt and initiatives
A project has a lead, members, teams, start and target dates, milestones, documents, resource links and status updates. Each update carries a health (on track, at risk, off track) that becomes the project's health.
The Gantt tab shows the project's scheduled issues as bars, grouped by milestone. Drag a bar to move it, drag its edges to change the start or due date, drag a milestone diamond to change its date. Blocking relations draw as arrows, red when the dependent work starts too early. Unscheduled issues wait on the right : click one to schedule it from today.
Initiatives group projects behind a goal, as a list or a board.
Integrations
GitHub : Settings → Integrations, turn GitHub on, then add a repository webhook with the payload URL and secret shown. Mention an issue ID (like ENG-12) in a branch name, PR title or commit message to link it. Opening a PR moves the issue to In Review, merging moves it to Done.
Slack : paste an incoming webhook URL for project updates, and per team in team settings for new issues and status changes.
Email : set the SMTP_* variables on the server for invites, password resets and notification emails.
Importing from Linear
Settings → Import & export → Import from Linear. Paste a personal Linear API key, run a dry run to see the counts, then the real import. Issue IDs, statuses, labels, cycles, projects, milestones, initiatives, comments, relations, links and documents come over. People appear as members you can invite later. Re-running updates what was imported.
The mobile app
Meridian installs on your phone as an app, full screen with its own icon.
- Android (Chrome) : open Meridian, then tap Install Meridian in the menu or the install banner.
- iPhone (Safari) : tap Share, then Add to Home Screen.
- Desktop (Chrome, Edge) : click the install icon in the address bar.
Long-press the icon for the New issue, Inbox and My issues shortcuts. When the network drops, the app keeps showing your workspace; edits need a connection.
Plans
Free covers 5 members, 2 teams and 250 active issues. Pro and Business raise the limits and add guests, the API, integrations and more storage. Payment is arranged with the Meridian team; your plan, seats and renewal date show in Settings → Plan & usage. A plan that ends keeps working for 14 days, then the workspace becomes read-only until it is renewed. Nothing is deleted.
Self-hosting
Meridian is a Next.js app and a Postgres database. With Docker :
docker compose -f docker-compose.prod.yml up -dSet APP_URL, APP_SECRET, ADMIN_EMAIL and ADMIN_PASSWORD. The admin panel at /admin manages workspaces, plans and payments. See the README in the repository for Coolify.