`nkapp shell`

Open an interactive terminal session inside a running service or database container.

nkapp shell is the ultimate debugging tool for your Nanokit applications. It provides a seamless interface to dive into your containers, whether they are running locally, on a remote VPS via SSH, or in the cloud.

Usage


nkapp shell [service-name] [options]

Arguments

Argument	Description
`service-name`	The name of the service or database you want to connect to.

Options

Option	Description
`-e, --env <env>`	Target environment (e.g., `local`, `test-kama`, `production`). Defaults to `local`.
`-d, --db`	Target a database resource instead of a standard service.
`-c, --command <cmd>`	Override the default shell command (e.g., `/bin/bash` or `ls`).

Interactive Services

By default, nkapp shell targets services. It automatically detects the best available shell (falling back to sh if bash is missing).


# Connect to the website service in the local environment
nkapp shell website
 
# Connect to a service in a remote environment
nkapp shell api --env production

Remote Connectivity (SSH Tunneling)

When targeting a remote environment (like a VPS), Nanokit automatically:

Establishes a secure SSH tunnel to the remote Docker daemon.
Identifies the correct container ID on the remote host.
Injects the DOCKER_HOST environment variable locally to route the command through the tunnel.

Database Inspection (`--db`)

One of the most powerful features of the shell command is the ability to connect directly to your databases to inspect raw data.


# Connect to a MongoDB database
nkapp shell my_mongo_db --db
 
# Run a specific query directly
nkapp shell my_mongo_db --db -c "mongosh --quiet --eval 'db.stats()'"

Automatic CLI Detection

When using the --db flag, Nanokit inspects the database engine and automatically runs the appropriate CLI tool. If the tool contains spaces or pipes, Nanokit transparently executes it via sh -c for maximum compatibility.

Engine	Tool Used
MongoDB	`mongosh`
PostgreSQL	`psql -U postgres`
Redis	`redis-cli`
MySQL / MariaDB	`mysql` / `mariadb`

If the specialized database tool is not found inside the container, it falls back to a standard shell (sh).

Cloud Databases (Neon & Turso) — planned (roadmap.v3)

Managed Neon and Turso are not selectable engines today (deferred pending real-account validation, roadmap.v3). When reactivated, nkapp shell would proxy via their respective CLI tools; until then, use their web consoles or local CLI wrappers.

Technical Details

Live Discovery: Unlike other commands that rely solely on the .nanokit/services-state.json file, shell performs Hybrid Discovery. It merges the local state with a live scan of the Docker daemon. This allows you to connect to containers that were just created or are out-of-sync with the local state file.
Complex Commands: The -c, --command flag now supports complex shell strings, including pipes (|) and redirects. Nanokit intelligently detects these and wraps them in an execution context (like sh -c) to ensure they run as expected inside the container.
TTY Handling: Nanokit delegates TTY handling directly to the system’s docker or aws binary. This ensures that features like tab-completion, window resizing, and keyboard signals (like Ctrl+C) work exactly as expected.
AWS ECS Support: When running in an AWS environment, the command automatically leverages ECS Execute Command to open a session in the Fargate task.

nkapp shell