CLI Reference

pocketdock includes a full CLI for managing containers from the terminal.

Install

pip install pocketdock

Global Options

Option	Env Var	Description
--socket PATH	POCKETDOCK_SOCKET	Container engine socket path
--verbose / -v	—	Enable verbose output
--version	—	Show version and exit
--help	—	Show help and exit

Getting Started

quickstart

Print getting-started instructions.

pocketdock quickstart

Project Commands

init

Initialize a .pocketdock/ project directory.

pocketdock init [PATH]

Option	Description
PATH	Directory to initialize (default: current directory)

status

Show project summary and container states.

pocketdock status [--json]

doctor

Diagnose orphaned containers and stale instance directories.

pocketdock doctor [--json]

logs

View command history for the project.

pocketdock logs [--json] [--history] [--follow] [--limit N]

Option	Description
--history	Show command history
--follow	Follow log output
--limit N	Limit number of entries

Container Lifecycle

create

Create a new container.

pocketdock create [OPTIONS]

Option	Description
--image IMAGE	Container image (default: pocketdock/minimal-python)
--name NAME	Container name (auto-generated if omitted)
--profile PROFILE	Image profile (minimal-python, minimal-node, minimal-bun, dev, agent, embedded)
--mem-limit LIMIT	Memory limit (e.g., 256m, 1g)
--cpu-percent N	CPU cap as percentage
--persist	Make container persistent
--device DEVICE	Device passthrough (can be repeated)
--port / -p HOST:CONTAINER	Port mapping (can be repeated)

pocketdock create --name my-sandbox --profile dev --mem-limit 512m --persist
pocketdock create --name web -p 8080:80 -p 3000:3000

run

Execute a command inside a container.

pocketdock run CONTAINER [OPTIONS] COMMAND...

Option	Description
--stream	Stream output in real time
--detach	Run in background
--timeout N	Command timeout in seconds
--lang LANG	Language wrapper (e.g., python)

pocketdock run my-sandbox echo hello
pocketdock run my-sandbox --stream make all
pocketdock run my-sandbox --detach python server.py
pocketdock run my-sandbox --lang python "print(2 + 2)"

shell

Open an interactive shell session.

pocketdock shell CONTAINER

This passes through to the engine's exec -it command (e.g., docker exec -it CONTAINER /bin/sh).

reboot

Restart a container.

pocketdock reboot CONTAINER [--fresh]

Option	Description
--fresh	Recreate from scratch (new filesystem)

stop

Stop a running container without removing it.

pocketdock stop CONTAINER

resume

Resume a stopped persistent container.

pocketdock resume CONTAINER

shutdown

Stop and remove a container.

pocketdock shutdown CONTAINER [--yes]

Option	Description
--yes / -y	Skip confirmation prompt

snapshot

Commit a container's filesystem as a new image.

pocketdock snapshot CONTAINER IMAGE_NAME

pocketdock snapshot my-sandbox my-sandbox:v1

prune

Remove all stopped pocketdock containers.

pocketdock prune [--yes] [--project PROJECT]

Option	Description
--yes / -y	Skip confirmation prompt
--project PROJECT	Only prune containers for this project

Information Commands

list

List all pocketdock managed containers.

pocketdock list [--json] [--project PROJECT]

pocketdock list
pocketdock list --json
pocketdock list --project my-app

info

Show detailed information about a container.

pocketdock info CONTAINER [--json]

File Operations

push

Copy a file or directory from the host into a container.

pocketdock push CONTAINER SRC DEST

pocketdock push my-sandbox ./src/ /home/sandbox/src/

pull

Copy a file or directory from a container to the host.

pocketdock pull CONTAINER SRC DEST

pocketdock pull my-sandbox /home/sandbox/output.csv ./output.csv

Image Profile Commands

profiles

List available image profiles.

pocketdock profiles [--json]

build

Build profile images from Dockerfiles.

pocketdock build [PROFILE]

pocketdock build           # Build all profiles
pocketdock build minimal-python   # Build a specific profile

export

Save images to a tar/tar.gz file for transfer.

pocketdock export [OPTIONS] -o OUTPUT

Option	Description
--all	Export all profile images
-o / --output FILE	Output file path

pocketdock export --all -o images.tar.gz

import

Load images from a tar/tar.gz file.

pocketdock import FILE

pocketdock import images.tar.gz

JSON Output

Read commands support --json for machine-readable output:

pocketdock list --json
pocketdock info my-sandbox --json
pocketdock doctor --json
pocketdock status --json
pocketdock logs --json
pocketdock profiles --json