Skip to content

DOCS.md

Latest commit

 

History

History
647 lines (460 loc) · 16.9 KB

DOCS.md

File metadata and controls

647 lines (460 loc) · 16.9 KB

Miko Shell Documentation

Comprehensive user and operator guide for the miko-shell CLI. This document is the canonical reference; for a quick overview, see the project README.

1. Introduction

miko-shell packages your project into### 4.3 Image caching and tagging

miko-shell computes a short hash of your config and tags the built image as:

<normalized-name>:<config-hash>

When the config changes, a new tag is built; otherwise the existing image is reused.

4.4 Runtime environment

  • The repository is mounted at /workspace
  • The working directory is /workspace
  • Host details are available to scripts when needed (for example via environment variables if provided by the wrapper). Typical variables:
    • MIKO_HOST_OS, MIKO_HOST_ARCH (when supported)

4.5 Docker and Podmantainer sExit codes: infrastructure errors (e.g., config invalid, engine missing) are returned with explanatory messages; script command failures propagate the command's exit code without extra help output.

1.1 Principles

  • Reproducible: deterministic image tag from config hash
  • Minimal host impact: no global installs; everything inside the container
  • Familiar: plain YAML; Docker or Podman under the hood
  • Fast feedback: caches layers and keeps startup simple

1.2 Core workflow

miko-shell.yaml  ->  build image  ->  run scripts / ad‑hoc commands

2. Installation

2.1 Quick Install (Recommended)

Install via script:

curl -sSL https://raw.githubusercontent.com/jepemo/miko-shell/main/install.sh | bash

Options:

  • Pin a version:

    curl -sSL https://raw.githubusercontent.com/jepemo/miko-shell/main/install.sh | bash -s -- --version v1.0.0

  • Uninstall completely:

    curl -sSL https://raw.githubusercontent.com/jepemo/miko-shell/main/install.sh | bash -s -- --uninstall

  • Custom install directory:

    export BIN_DIR="$HOME/bin"
curl -sSL https://raw.githubusercontent.com/jepemo/miko-shell/main/install.sh | bash

The script detects your OS/arch, fetches the release asset, and falls back to building from source if no asset matches.

2.2 From source (Go >= 1.23)

make build
# or
go build -o miko-shell .

2.3 Bootstrap script (No Go required)

For systems without Go installed, use the bootstrap script that downloads Go and builds the project:

# Build the project (downloads Go if needed)
./bootstrap.sh

# Show help and all available options
./bootstrap.sh --help

Bootstrap Options

The bootstrap script supports several useful options:

  • ./bootstrap.sh — Default behavior: build the project (downloads Go 1.23.4 if needed)

  • ./bootstrap.sh --clean — Clean build artifacts, similar to make clean but also removes:

    • miko-shell binary
    • miko-shell-host binary
    • build/ directory
    • .bootstrap/ directory

  • ./bootstrap.sh --clean-images — Remove all Docker/Podman images starting with 'miko-shell':

    • miko-shell:* (any tag)
    • miko-shell-dev:*
    • miko-shell-test:*
    • Any image beginning with miko-shell

  • ./bootstrap.sh --help — Show detailed usage information

Examples

# Clean everything and rebuild
./bootstrap.sh --clean
./bootstrap.sh

# Clean only container images
./bootstrap.sh --clean-images

# Full cleanup (build artifacts + images)
./bootstrap.sh --clean
./bootstrap.sh --clean-images
./bootstrap.sh  # rebuild

The bootstrap script is particularly useful for:

  • CI environments without Go pre-installed
  • Development on new machines
  • Consistent builds across different environments

2.4 Prebuilt binaries

Download from Releases and place on your PATH as miko-shell.

2.5 Verify

miko-shell --help
miko-shell version

3. Quick Start

# 1) Scaffold a config
miko-shell init               # or: miko-shell init --dockerfile

# 2) Build the image (optional – auto-build on first run)
miko-shell image build

# 3) List available scripts
miko-shell run

# 4) Run a script
miko-shell run test

# 5) Run an ad‑hoc command (everything after -- goes verbatim)
miko-shell run -- go env

Minimal miko-shell.yaml:

name: my-project
container:
  provider: docker
  image: alpine:latest
  setup:
    - apk add --no-cache bash curl git
shell:
  startup:
    - echo "Welcome to my-project shell"
  scripts:
    - name: test
      commands:
        - go test ./...
    - name: greet
      commands:
        - echo "Hello $1, you are $2 years old"

4. Concepts and Architecture

4.1 Configuration model

Top-level keys:

  • name — project label; also used for image tagging
  • container — how to build or select the base image
  • shell — what to run on startup and named scripts to expose

Container section:

  • provider: docker (default) or podman
  • image: base image to use if you’re not building
  • build (optional): custom image build
    • dockerfile: path to Dockerfile
    • context: build context (default: ".")
    • args: map of build-args
  • setup: list of commands executed at image build time (install deps)

Shell section:

  • startup: commands executed on every run
  • scripts[]:
    • name: script name to call via miko-shell run <name>
    • description (optional)
    • commands[]: commands executed inside the container. Positional $1, $2, … map to arguments.

4.2 Environment Variables

miko-shell automatically captures and persists environment variables exported during startup, making them available to all scripts.

Automatic Variable Persistence

Any variables exported in the startup section are automatically captured and made available to:

  • All scripts executed via miko-shell run <script>
  • Interactive shell sessions via miko-shell open

Example:

shell:
  startup:
    - export PROJECT_VERSION=1.2.3
    - export DATABASE_URL=postgres://user:pass@localhost/db
    - export DEBUG_MODE=true
  scripts:
    - name: build
      commands:
        - echo "Building version: $PROJECT_VERSION"
        - echo "Debug mode: $DEBUG_MODE"
    - name: deploy
      commands:
        - echo "Deploying to: $DATABASE_URL"

How it works

  1. Before startup: Environment state is captured
  2. During startup: Your export commands are executed
  3. After startup: Changes are detected and automatically persisted to /etc/profile.d/miko-shell-env.sh
  4. Script execution: All scripts inherit these variables automatically

Best Practices

  • Use startup for environment variables that should be available to all scripts
  • Export project-specific configuration (versions, URLs, flags)
  • Avoid exporting sensitive data; use runtime injection for secrets instead

4.3 Image caching and tagging

miko-shell computes a short hash of your config and tags the built image as:

<normalized-name>:<config-hash>

When the config changes, a new tag is built; otherwise the existing image is reused.

4.3 Runtime environment

  • The repository is mounted at /workspace
  • The working directory is /workspace
  • Host details are available to scripts when needed (for example via environment variables if provided by the wrapper). Typical variables:
    • MIKO_HOST_OS, MIKO_HOST_ARCH (when supported)

4.4 Docker and Podman

Choose your engine via container.provider. Everything else works the same.

5. Command Reference

Global flags:

  • -c, --config: path to config (default: miko-shell.yaml)

5.1 init

Scaffold a new config.

miko-shell init           # prebuilt base image + setup commands
miko-shell init --dockerfile  # Dockerfile-driven build

5.2 run

Run a named script or an ad‑hoc command inside the container.

# List available scripts (no args)
miko-shell run

# Run a named script
miko-shell run test
miko-shell run greet Alice 42

# Ad‑hoc command (everything after -- is passed verbatim)
miko-shell run -- go env

Exit codes: infrastructure errors (e.g., config invalid, engine missing) are returned with explanatory messages; script command failures propagate the command's exit code without extra help output.

5.3 open

Open an interactive shell inside the development environment.

miko-shell open
miko-shell open -c examples/dev-config-go.example.yaml

This provides direct access to the containerized environment for debugging, exploration, or manual operations.

5.4 image

Comprehensive container image management with multiple subcommands.

# Build container image
miko-shell image build
miko-shell image build --force  # Force rebuild

5.3 run

Run a named script or an ad‑hoc command inside the container.

# List available scripts (no args)
miko-shell run

# Run a named script
miko-shell run test
miko-shell run greet Alice 42

# Ad‑hoc command (everything after -- is passed verbatim)
miko-shell run -- go env

Exit codes: infrastructure errors (e.g., config invalid, engine missing) are returned with explanatory messages; script command failures propagate the command’s exit code without extra help output.

5.4 open

Open an interactive shell inside the development environment.

miko-shell open
miko-shell open -c examples/dev-config-go.example.yaml

This provides direct access to the containerized environment for debugging, exploration, or manual operations.

5.5 image

Comprehensive container image management with multiple subcommands.

# Build container image
miko-shell image build
miko-shell image build --force  # Force rebuild

# List miko-shell images
miko-shell image list
miko-shell image ls              # Alias

# Clean unused images
miko-shell image clean
miko-shell image clean --all     # Remove all miko-shell images

# Show detailed image information
miko-shell image info            # Current project's image
miko-shell image info <image-id> # Specific image

# Prune all unused images and build cache
miko-shell image prune
miko-shell image prune --force   # Skip confirmation

The image command provides a modern, Docker-like interface for managing container images:

  • build: Same functionality as the previous standalone build command with improved UX
  • list: View all miko-shell related images with metadata
  • clean: Remove unused images to reclaim disk space
  • info: Inspect image details, layers, and configuration
  • prune: System-wide cleanup of unused images and build cache

5.5 version

Show version information.

miko-shell version

5.6 completion

Generate shell autocompletion scripts for enhanced command-line experience.

# Generate completion for bash
miko-shell completion bash

# Generate completion for zsh
miko-shell completion zsh

# Generate completion for fish
miko-shell completion fish

# Generate completion for PowerShell
miko-shell completion powershell

To enable autocompletion, follow the instructions provided by the command output for your specific shell.

6. Examples Library

The examples/ directory includes ready‑to‑use configs for:

  • Go, Python, Node/Next.js, Rust
  • Ruby/Rails, PHP/Laravel
  • Elixir/Phoenix, Django, Java/Spring Boot

Use them directly with -c or copy to your project as a starting point. See examples/README.md and examples/USAGE.md.

6.1 Environment Variables Example

Here's a practical example showing automatic environment variable persistence:

name: my-app
container:
  provider: docker
  image: node:18-alpine
  setup:
    - npm install -g typescript @types/node
shell:
  startup:
    # These variables will be automatically available to all scripts
    - export PROJECT_VERSION=2.1.0
    - export NODE_ENV=development
    - export API_BASE_URL=https://api.example.com
    - export DEBUG_MODE=true
    - echo "Environment configured for $NODE_ENV"
  scripts:
    - name: build
      description: Build the application
      commands:
        - echo "Building version $PROJECT_VERSION for $NODE_ENV"
        - npm run build
        - echo "Build completed for version $PROJECT_VERSION"

    - name: test
      description: Run tests with environment context
      commands:
        - echo "Running tests in $NODE_ENV mode"
        - echo "API URL: $API_BASE_URL"
        - echo "Debug enabled: $DEBUG_MODE"
        - npm test

    - name: deploy
      description: Deploy application
      commands:
        - echo "Deploying version $PROJECT_VERSION"
        - echo "Target environment: $NODE_ENV"
        - echo "API endpoint: $API_BASE_URL"
        # Deploy commands would use these variables

Usage:

# All scripts automatically have access to the startup variables
miko-shell run build    # Uses PROJECT_VERSION, NODE_ENV, etc.
miko-shell run test     # Same variables available
miko-shell run deploy   # Variables persist across all script executions

7. Configuration Patterns

7.1 Prebuilt base image + setup

container:
  provider: docker
  image: golang:1.23-alpine
  setup:
    - apk add --no-cache make git

7.2 Custom Dockerfile build

container:
  provider: docker
  build:
    dockerfile: Dockerfile
    context: .
    args:
      NODE_VERSION: "20"
  setup:
    - npm i -g pnpm

7.3 Scripts and arguments

shell:
  startup:
    - echo "Starting dev environment"
  scripts:
    - name: dev
      description: Run dev server
      commands:
        - npm run dev
    - name: greet
      commands:
        - echo "Hello $1"

Call as miko-shell run greet Alice -> prints Hello Alice.

8. CI/CD usage

Run the same scripts in CI without installing language toolchains on runners.

GitHub Actions (minimal):

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build image
        run: |
          miko-shell image build
      - name: Test
        run: |
          miko-shell run test

GitLab CI:

stages: [build, test]

build:
  stage: build
  image: docker:stable
  services: [docker:dind]
  script:
    - miko-shell image build

test:
  stage: test
  image: docker:stable
  services: [docker:dind]
  script:
    - miko-shell run test

9. Troubleshooting

Symptom Likely cause Fix
miko-shell.yaml not found Missing config Run miko-shell init or pass -c
invalid provider Typo in container.provider Use docker or podman
Engine not found Docker/Podman not installed/running Install and start your engine
Script not listed Name mismatch Run miko-shell run to list; check shell.scripts[].name
Command exits with non‑zero Command failed inside container Fix the underlying command; exit code is preserved
Too many cached images Multiple miko-shell builds Use miko-shell image clean or miko-shell image prune
Disk space issues Build artifacts accumulation Use miko-shell image prune for complete cleanup

9.1 Maintenance Commands

For ongoing maintenance and cleanup:

# Clean build artifacts (binaries, temp directories)
./bootstrap.sh --clean

# Clean all miko-shell container images
./bootstrap.sh --clean-images

# Full cleanup and rebuild
./bootstrap.sh --clean
./bootstrap.sh --clean-images
./bootstrap.sh

# Using miko-shell image build with force rebuild
miko-shell image build --force  # Removes existing image and rebuilds

# Modern image management commands
miko-shell image list     # See all miko-shell images
miko-shell image clean    # Remove unused images
miko-shell image clean --all  # Remove all miko-shell images
miko-shell image prune    # System-wide cleanup with confirmation
miko-shell image prune --force  # System-wide cleanup without confirmation
miko-shell image info     # Inspect current project's image

10. FAQ

Q: Docker or Podman?

A: Both are supported — set container.provider accordingly.

Q: How do I pass arguments to scripts?

A: Positional arguments are available as $1, $2, … inside each command in commands[].

Q: Where does it run?

A: All commands run inside the container with your project mounted at /workspace.

Q: Do I need to run build first?

A: Not strictly — the first run/open will build if needed. Running build proactively helps surface build errors early.

Q: How do I get an interactive shell?

A: Use miko-shell open to get a shell inside the development environment.

Q: What's the difference between build and image build?

A: Both do the same thing. image build is the modern interface with additional flags and better UX. Use image commands for comprehensive image management.

11. License

MIT. See LICENSE.

12. Links

  • Examples: examples/
  • README (overview): README.md