`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)

For cloud-native engines like Neon and Turso, nkapp shell will soon support direct proxying via their respective CLI tools. Currently, we recommend using 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