# CLI reference > The logdeck CLI: install it, log in with contexts and API tokens, then read, follow, and grep logs and manage containers from the terminal. `logdeck` is the command-line client for a running LogDeck server. It talks to the same HTTP API as the web interface, so the containers, logs, stats, events, and Compose stacks you see in the UI are all available from the terminal. It is fully non-interactive and built for scripting and AI agents. Every command supports machine-readable JSON output (`-o json`), errors always go to stderr, and exit codes are consistent: 0 for success, 1 for a runtime error, 2 for a usage error. ## Install Install the latest release binary (macOS and Linux, amd64/arm64): ```bash curl -fsSL https://raw.githubusercontent.com/AmoabaKelvin/logdeck/main/install.sh | sh ``` Binaries ship on [GitHub Releases](https://github.com/AmoabaKelvin/logdeck/releases) with checksums. The installer picks the right one for your OS and architecture, verifies it against the release's `checksums.txt`, and installs it to `/usr/local/bin` or `~/.local/bin`. Check your version with `logdeck --version`. Or build from source. The CLI lives in the same Go module as the server and builds to a single static binary: ```bash cd server go build ./cmd/logdeck ./logdeck --help ``` ## Connection and authentication Connect once with `logdeck login`. It verifies the connection (a health check, plus an authenticated call when you pass a token) and saves it as a named context, kubectl-style. From then on every command uses that context: ```bash logdeck login --url https://logdeck.example.com --token ldk_... --name prod logdeck status # now talks to prod ``` Contexts persist in `~/.config/logdeck/config.json` (respecting `XDG_CONFIG_HOME`). The file stores API tokens, so the CLI creates it with `0600` permissions inside a `0700` directory. It never prints a saved token, only its `ldk_` prefix. Manage contexts with: ```bash logdeck context list # name, url, token prefix, current marker logdeck context use staging # switch the current context logdeck context rm old # delete a context logdeck logout # remove the token from the current (or named) context, keeping its URL ``` Create API tokens in the LogDeck web UI under **Settings > API Access**. The CLI sends them as `Authorization: Bearer `. Tokens have a scope. **Admin** tokens have full access. **Read-only** tokens can read logs, stats, container details, and events, but cannot mutate anything, use the web terminal, or read container environment variables or settings. That makes them a good fit for CI jobs and AI agents that only need to read. When the server has authentication disabled, no token is needed. On a 401 response, the CLI tells you to authenticate with an API token created in LogDeck Settings, passed with `--token` or `LOGDECK_TOKEN`. ### Resolution order Flags and environment variables override the saved context, which helps in CI or for one-off calls. The URL and the token resolve independently, each from the first source that provides it: 1. Explicit `--url` / `--token` flags 2. `LOGDECK_URL` / `LOGDECK_TOKEN` environment variables 3. The active context from the config file (`--context ` selects another saved context for one invocation) 4. Default `http://localhost:8080` `logdeck status` shows which source supplied the URL and the token. ## Output formats Every command accepts `-o/--output`: - `table` (default): compact aligned columns for humans. - `json`: a single JSON document for one-shot commands, and NDJSON (one JSON object per line) for streaming commands (`logs --follow`, `events`). Timestamps are RFC3339. There are no colors, spinners, prompts, or pagination. ## Commands ### `login` Verify a server connection and save it as the current context. If the server requires authentication and you give no working token, it fails with a hint pointing at Settings. ```bash logdeck login --url https://logdeck.example.com --token ldk_... --name prod ``` ### `context` Manage saved contexts: `list`, `use `, `rm `. ```bash logdeck context list ``` ### `logout` Remove the saved token from the current (or a named) context, keeping its URL. ```bash logdeck logout prod ``` ### `status` Server health, version, and a per-host summary, plus where the connection settings came from (flag, env, or context). Run it first to discover what a server manages. Exits nonzero if the server is unreachable. ```bash logdeck status ``` ### `containers` List containers across all hosts, with optional filters. ```bash logdeck containers --state running --host prod ``` ### `stacks` List Compose projects, grouped by the `com.docker.compose.project` / `io.podman.compose.project` labels, with container counts and hosts. ```bash logdeck stacks ``` ### `inspect` Full inspect data for one container. Table mode shows key facts. `-o json` prints the complete inspect document. ```bash logdeck inspect web -o json ``` ### `logs` Read or follow the parsed logs of a container, or of a whole Compose stack with `--stack`. `--since` and `--until` accept RFC3339 timestamps or relative durations (`30s`, `15m`, `2h`, `1d`). Stack logs merge by timestamp and show the container name on each line. Following a stack covers its first 20 containers, the server's per-request aggregate limit. One-shot stack reads batch beyond that automatically. ```bash logdeck logs web --tail 200 --level ERROR --since 1h logdeck logs web --follow logdeck logs --stack myapp --search "timeout" --since 30m ``` ### `grep` Search the recent logs of every running container across all hosts, merged by timestamp. It looks at the last 15 minutes by default so it stays fast. ```bash logdeck grep "connection refused" --since 1h --level ERROR ``` An empty result still exits 0. Stdout stays empty, so pipelines stay clean, and a one-line hint goes to stderr: `no running containers to search` or `no matches in containers since