smartem-workspace

CLI tool to automate SmartEM multi-repo workspace setup.

Installation

# Run directly with uvx (recommended)
uvx smartem-workspace init

# Or install globally
uv tool install smartem-workspace

Usage

Global options

--no-color          Disable colored output
--plain             Plain mode: no color, no interactive prompts

Initialize a new workspace

# Interactive setup in current directory
smartem-workspace init

# Specify target directory
smartem-workspace init --path ~/dev/smartem

# Use a preset (skip repo selection)
smartem-workspace init --preset smartem-core

# Non-interactive with preset
smartem-workspace init --preset full --no-interactive

Available presets

Verify workspace setup

# Check all configuration
smartem-workspace check

# Check specific scope
smartem-workspace check --scope claude
smartem-workspace check --scope repos
smartem-workspace check --scope serena

# Auto-repair fixable issues (broken symlinks, missing dirs)
smartem-workspace check --fix

Sync repositories

# Pull latest from all cloned repos
smartem-workspace sync

# Preview what would be pulled
smartem-workspace sync --dry-run

Sync skips repos with uncommitted changes or not on main/master branch.

Other commands

# Show workspace status (alias for check)
smartem-workspace status

# Set up Claude Code integration (after init without --with-claude)
smartem-workspace claude setup

# Add a single repo (not yet implemented)
smartem-workspace add DiamondLightSource/smartem-frontend

Init options

--path PATH         Target directory (default: current directory)
--preset NAME       Use preset: smartem-core, full, aria-reference, minimal
--no-interactive    Skip prompts, use preset only
--git-ssh           Force SSH URLs for all repos
--git-https         Force HTTPS URLs (skip auto-detection)
--with-claude       Enable Claude Code integration setup
--skip-serena       Skip Serena MCP setup
--skip-dev-requirements  Skip developer requirements check

Git URL auto-detection: By default, the CLI automatically detects if you have SSH authentication configured for GitHub. If SSH works, repos are cloned via SSH (enabling push); otherwise HTTPS is used (read-only). Use --git-ssh or --git-https to override.

Check options

--scope SCOPE       Check scope: dev-requirements, claude, repos, serena, or all (default: all)
--fix               Attempt to fix issues (recreate symlinks, dirs)
--offline           Use bundled config instead of fetching from GitHub

Sync options

--dry-run, -n       Show what would be done without making changes

What it sets up

1. Repository clones - Organized by organization (DiamondLightSource, FragmentScreen, GitlabAriaPHP)
2. Claude Code configuration (with --with-claude) - Skills, settings, permissions
3. Serena MCP server - Semantic code navigation
4. Workspace structure - tmp/, testdata/ directories

Documentation

• User Guide: Setup SmartEM Workspace
• Developer Guide: Contributing to smartem-workspace
• PyPI Setup: Publishing to PyPI
• API Documentation: SmartEM Devtools Docs

Development

cd packages/smartem-workspace

# Install dev dependencies
uv sync --all-extras

# Run tests
uv run pytest

# Run linter
uv run ruff check .

# Build package
uv build

See Developer Guide for detailed development instructions.

Releasing

Releases are published to PyPI via GitHub Actions using Trusted Publishers.

# 1. Update version in pyproject.toml
# 2. Commit the change
git commit -am "chore: release smartem-workspace vX.Y.Z"

# 3. Create and push a version tag
git tag smartem-workspace-vX.Y.Z
git push origin main --tags

The CI workflow runs tests, builds the package, and publishes to PyPI automatically on tag push.

Links

• PyPI: https://pypi.org/project/smartem-workspace/
• Repository: https://github.com/DiamondLightSource/smartem-devtools
• Issues: https://github.com/DiamondLightSource/smartem-devtools/issues
• Changelog: GitHub Releases

License

Apache-2.0