Shells

A shell launches an interactive session with a pre-configured environment. Instead of remembering which env vars to export before debugging staging or switching between projects, you define the context once and drop into it with one command.

Basic shell

version: v1

shells:
  dev:
    description: "Development environment"
    env:
      NODE_ENV:
        type: string
        default: development
      DATABASE_URL:
        type: string
        default: "postgresql://localhost:5432/myapp_dev"
      PORT:
        type: string
        default: "3000"

Start it:

meriadoc run shell dev
# or shorter:
meriadoc shell dev
meriadoc s dev

Your shell opens with all declared env vars already set. Exit normally (exit or Ctrl-D) to return.

Init commands

Run commands before handing control to the user:

shells:
  staging:
    description: "Staging environment"
    env:
      K8S_CONTEXT:
        type: string
        default: staging-cluster
      AWS_PROFILE:
        type: string
        default: staging
    init_cmds:
      - kubectl config use-context $K8S_CONTEXT
      - aws sts get-caller-identity
      - echo ""
      - echo "Staging Environment Active"
      - echo "Context: $K8S_CONTEXT  |  AWS: $AWS_PROFILE"

Init commands run in the same environment as the shell, so they have access to all declared env vars.

Working directory

By default, the shell opens in the directory you invoked meriadoc from (unlike tasks, which default to the spec file’s directory). Override with workdir:

shells:
  backend:
    workdir: services/api
    env:
      DEBUG: "true"

Env files

Load env files the same way as tasks:

shells:
  local:
    env_files:
      - .env
      - .env.local
    init_cmds:
      - echo "Loaded local env"

Dry run

Preview what the shell would set up without actually launching it:

meriadoc run shell dev --dry-run

Shows resolved env vars, init commands, and the working directory.

Production shells

For high-stakes environments, add a strong visual warning in init_cmds:

shells:
  production:
    description: "Production environment — use with caution"
    env:
      K8S_CONTEXT:
        type: string
        default: prod-cluster
      AWS_PROFILE:
        type: string
        default: production
    init_cmds:
      - kubectl config use-context $K8S_CONTEXT
      - echo "======================================="
      - echo "  ⚠  PRODUCTION ENVIRONMENT"
      - echo "  Changes affect real users!"
      - echo "======================================="