CLI¶

pip install klangkc

klangkc login http://myhost:8995 admin@example.com
# Creates ~/.config/klangk/cli.yaml with:
#   servers:
#     myhost:
#       url: http://myhost:8995
#       user: admin@example.com

# Authentication
klangkc login local                          # login to "local" alias (uses default user from config)
klangkc login http://localhost:8995          # login with a raw URL (prompts for user)
klangkc login prod chris@example.com         # login as a specific user
klangkc logout                               # logout from active server
klangkc logout prod                          # logout from a specific server
klangkc status                               # show active server and user

# Non-interactive login (for scripts)
klangkc login prod admin --password-file /path/to/pwfile
echo "secret" | klangkc login prod admin --password-file -

# Working with a non-default server
klangkc --server=prod ls                     # list workspaces on prod
klangkc --server=prod shell my-project       # connect to shell on prod

# Workspaces
klangkc ls                               # list workspaces (first page)
klangkc ls --shared                      # include workspaces shared with you
klangkc ls --limit 50                    # list up to 50 per section
klangkc ls --all                         # page through every workspace
klangkc ls --sort name --order asc       # sort by name, ascending
klangkc ls --filter gamma                # substring filter on name
klangkc create my-project                # create a workspace
klangkc create my-project --auto-start   # create with auto-start on server boot
klangkc create my-project --mount ~/src:/home/klangk/work/src          # with bind mount
klangkc create my-project --mount nix-store:/nix           # with named volume
klangkc create my-project --env FOO=bar                      # with env vars
klangkc create my-project --health-check 'curl -sf http://localhost:8080/health'  # with a service health check
klangkc create my-project --command 'npm run dev'  # with a service command
klangkc create my-project -c 'npm run dev'         # short form of --command
klangkc edit my-project                  # interactive edit (name, image, command, health check, mounts, env)
klangkc edit my-project --auto-start     # enable auto-start on server boot
klangkc edit my-project --no-auto-start  # disable auto-start
klangkc edit my-project --env FOO=bar    # set env var via flag
klangkc dup my-project my-copy           # duplicate a workspace
klangkc shell my-project                 # drop into bash inside the container
klangkc shell my-project debug           # attach to the "debug" terminal window (created if it doesn't exist)
klangkc sandbox myws                     # create workspace from .klangk-sandbox.yaml
klangkc sandbox myws ~/projects/myapp    # specify sandbox root explicitly
klangkc sandbox myws --force             # re-apply config and re-run setup on existing workspace
klangkc exec my-project ls /home/klangk/work         # run a command in the container (login shell: sources ~/.profile)
klangkc exec --raw my-project rsync --server ...      # raw argv, no shell (for transports like rsync)
klangkc monitor                                        # stream all server events as JSON
klangkc monitor --type service_health | jq .           # pretty-print health transitions
klangkc monitor --type service_health -- sh -c '[ "$KLANGK_HEALTHY" = false ] && notify-send "klangk" "$KLANGK_HEALTH_MESSAGE"'  # alert with the failure reason
klangkc sync ~/src my-project:/home/klangk/work      # sync files to/from the container
klangkc rm my-project                # delete a workspace
klangkc restart my-project           # restart the container for a workspace (owner only)
klangkc export my-project            # export workspace to my-project.tar.gz (admin only)
klangkc export my-project -o bak.tar.gz  # export to specific file
klangkc import bak.tar.gz            # import workspace from archive
klangkc import bak.tar.gz --name new-name  # import with a different name

# Sharing
klangkc members my-project           # list workspace members by role
klangkc share my-project user@x.com  # share workspace (default: coder role)
klangkc share my-project user@x.com --role=spectator  # share with specific role
klangkc unshare my-project user@x.com # remove a user from all roles
klangkc terminal ls my-project       # list all terminals (own + shared)
klangkc terminal share my-project bash        # share a terminal with workspace members
klangkc terminal unshare my-project bash      # stop sharing a terminal

# Admin
klangkc invite user@example.com      # send an invitation email (admin only)
klangkc invitations                  # list all invitations (admin only)
klangkc images                       # list available container images
klangkc volumes ls                   # list your podman volumes
klangkc volumes create nix-store     # create a named volume (owned by you)
klangkc volumes rm nix-store         # delete a volume (must be yours)

klangkc shell my-project build    # attach to the "build" window
klangkc shell my-project logs     # attach to the "logs" window