Skip to main content

cockpit-cli

Keyboard-first developer workspace cockpit for Linux.

cockpit-cli combines a Textual TUI, a local web admin plane, persisted sessions, guarded mutating actions, and a plugin-capable datasource platform. The app is Linux-first and optimized for local development, SSH-backed environments, and operator workflows that need one command/event model across terminal, Git, Docker, Cron, DB, HTTP, and layout management.

Core Capabilities

  • persisted workspaces and sessions backed by SQLite
  • local and SSH-backed workspaces with resume across restarts
  • Textual TUI with Work, Git, Docker, Cron, DB, Curl, and Logs
  • editable split layouts with persisted variants
  • command palette, slash commands, and keybindings through one dispatcher
  • guarded mutating flows for Docker, Cron, DB, and HTTP actions
  • local web admin for datasource profiles, plugin installs, layouts, and diagnostics
  • Vault-first secret registry with compatibility providers for env, file, and keyring
  • plugin install/update/pin/remove with repo or package requirements
  • plugin compatibility, permission allowlists, and on-disk integrity verification before runtime activation
  • broad datasource support through SQLAlchemy dialects plus non-SQL adapters
  • terminal scrollback, search, keyboard or mouse-assisted selection, export, and clipboard copy

Supported Datasource Families

Built-in datasource profiles support these backends:

  • sqlite
  • postgres / postgresql
  • mysql
  • mariadb
  • mssql
  • duckdb
  • bigquery
  • snowflake
  • mongodb
  • redis
  • chromadb

Relational and analytics backends run through SQLAlchemy with external dialects where appropriate. Non-SQL backends use dedicated adapters. Additional datasources can be supplied by plugins.

Tech Stack

  • Python 3.11+
  • Textual
  • SQLite
  • YAML + TCSS
  • SQLAlchemy
  • optional Ibis and backend-specific drivers

Repository Layout

config/
  commands.yaml
  connections.example.yaml
  datasources.example.yaml
  keybindings.yaml
  layouts/
  plugins.example.yaml
  themes/
docs/
  superpowers/
packaging/
  arch/
src/cockpit/
tests/

Installation

Core install

git clone git@github.com:DamienDrash/cockpit_cli.git
cd cockpit_cli
python -m venv .venv
source .venv/bin/activate
pip install -e .

Full datasource install

pip install -e '.[all-datasources]'

Or install only the extras you need, for example:

pip install -e '.[postgres,mysql,duckdb,mongo,redis]'

Enable Vault, encrypted local cache support, and keyring compatibility:

pip install -e '.[vault,secrets]'

Install release and verification tooling:

pip install -e '.[release]'

Quick Start

Open the current directory:

cockpit-cli open .

Resume the last session:

cockpit-cli resume

List connection aliases:

cockpit-cli connections

List configured datasource profiles:

cockpit-cli datasources

Run the local web admin:

cockpit-cli admin --open-browser

TUI Commands

Common commands:

/workspace open .
/workspace open @prod:/srv/app
/workspace reopen_last
/session restore
/tab focus db
/layout apply_default
/layout toggle_orientation
/layout grow
/layout shrink
/terminal focus
/terminal restart
/terminal search "error"
/terminal search_next
/terminal search_prev
/terminal export .cockpit/terminal-buffer.txt
/terminal copy
/docker restart
/docker stop
/docker remove
/cron enable
/cron disable
/db run_query "SELECT 1"
/curl send GET https://example.com

Web Admin

The local web admin exposes:

  • datasource profile creation and deletion
  • datasource execution for quick operator queries and mutations
  • Vault profile management, login, lease diagnostics, transit actions, and managed secret references
  • plugin install/update/pin/enable/remove
  • layout cloning and split edits
  • diagnostics for commands, panels, datasources, secrets, plugins, tunnels, and tool availability

It runs locally only and reuses the same application services as the TUI.

Connection Profiles

Connection aliases live in config/connections.yaml. Start from connections.example.yaml.

Example:

connections:
  prod:
    target: deploy@example.com
    default_path: /srv/app
    description: Production target

Then open through either form:

cockpit-cli open --connection prod /srv/app
cockpit-cli open @prod:/srv/app/current

Datasource Profiles

Datasource profiles can be managed in the web admin or through config/datasources.yaml. Start from datasources.example.yaml.

Each profile captures:

  • backend
  • connection URL
  • optional secret reference mappings for ${PLACEHOLDER} interpolation
  • optional driver
  • risk level
  • local or SSH target
  • SSH tunneling for tunnel-safe remote SQL and NoSQL backends
  • database name
  • capabilities

Example secret-backed datasource snippet:

profiles:
  - id: analytics-postgres
    name: Analytics Postgres
    backend: postgres
    connection_url: postgresql+psycopg://${DB_USER}:${DB_PASS}@db.internal:5432/analytics
    target_kind: ssh
    target_ref: deploy@example.com
    secret_refs:
      DB_USER: env:ANALYTICS_DB_USER
      DB_PASS:
        provider: keyring
        service: cockpit
        username: analytics-password

Vault-backed references are also supported directly, for example:

```yaml
profiles:
  - id: app-postgres
    name: App Postgres
    backend: postgres
    connection_url: postgresql://${DB_USER}:${DB_PASS}@db.internal:5432/app
    secret_refs:
      DB_USER: vault+dynamic://ops-vault/database/app#username
      DB_PASS: vault+dynamic://ops-vault/database/app#password

## Plugin System

Two plugin paths exist:

1. Static config loading from `config/plugins.yaml`
2. Managed installs through the web admin using pip-compatible requirements

Managed plugin installs support:

- package names
- pinned versions
- local paths
- git requirements
- trusted source prefix enforcement
- permission allowlists before runtime activation
- compatibility checks against the running cockpit version
- install-time and runtime integrity hashes

Plugins can contribute:

- panels
- commands
- datasource families
- admin pages

See [plugins.example.yaml](/home/damien/Dokumente/cockpit/config/plugins.example.yaml)
and [notes_plugin.py](/home/damien/Dokumente/cockpit/src/cockpit/plugins/notes_plugin.py).

## Packaging

Release artifacts included in the repo:

- `sdist`
- `wheel`
- Arch/CachyOS `PKGBUILD` in [packaging/arch/PKGBUILD](/home/damien/Dokumente/cockpit/packaging/arch/PKGBUILD)
- tag-driven GitHub release workflow in [.github/workflows/release.yml](/home/damien/Dokumente/cockpit/.github/workflows/release.yml)
- release checksum manifest generation (`SHA256SUMS.txt`)
- CycloneDX SBOM generation for Python and frontend dependencies
- Sigstore keyless bundles for published release assets
- GitHub provenance attestation generation
- PyPI Trusted Publishing from the same canonical package artifacts

## Development

Run tests:

```bash
PYTHONPATH=src python -m unittest discover -s tests -p 'test_*.py' -v

Run UI/E2E tests with the dependency environment:

PYTHONPATH=src:/tmp/cockpit-deps python -m unittest \
  tests.e2e.test_embedded_terminal_widget \
  tests.e2e.test_app_resume_flow -v

CI lives in .github/workflows/ci.yml. It compiles the code, runs the unittest suite, builds sdist plus wheel, and runs a live service matrix against PostgreSQL, MySQL, Redis, and MongoDB. It also exercises a release dry-run path that builds the frontend bundle, assembles Python artifacts, and emits SBOM plus checksum metadata without publishing. Tagged pushes additionally publish release artifacts through .github/workflows/release.yml.

Release Verification

Published GitHub releases include:

  • sdist
  • wheel
  • SHA256SUMS.txt
  • release-manifest.json
  • Python and frontend CycloneDX SBOM files
  • Sigstore bundle files for release assets
  • GitHub build provenance bundle output

Verify checksums:

sha256sum -c SHA256SUMS.txt

Verify a signed artifact:

python -m pip install sigstore
python -m sigstore verify github cockpit_cli-<version>-py3-none-any.whl \
  --bundle cockpit_cli-<version>-py3-none-any.whl.sigstore.json \
  --repository DamienDrash/cockpit_cli \
  --ref refs/tags/v<version> \
  --trigger push

Verify provenance:

gh attestation verify cockpit_cli-<version>-py3-none-any.whl \
  --repo DamienDrash/cockpit_cli

Maintainer release steps are documented in docs/releasing.md.

Operator Notes

Terminal selection flow:

  • Ctrl+Space starts or clears a terminal line selection
  • Shift+Up and Shift+Down expand the active selection
  • Ctrl+Shift+C copies the selection
  • Ctrl+Alt+C copies the full terminal buffer
  • mouse wheel scrolls through scrollback
  • clicking and dragging inside the embedded terminal expands the current line selection

Managed secrets:

  • create them in the web admin under Secrets
  • reference them inside datasource secret_refs as stored:secret-name
  • Vault profiles support token, AppRole, and OIDC/JWT login modes
  • Vault-managed entries support kv and dynamic secret references
  • Vault transit operations are available from the web admin for encrypt/decrypt/sign/verify
  • Vault sessions can use encrypted local cache where enabled
  • compatibility env, file, and keyring providers remain supported for migration and bootstrap flows

Plugin trust policy:

  • config/plugins.yaml can define trusted_sources and allowed_permissions
  • plugins requesting permissions outside the configured allowlist stay installed but do not activate at runtime

Tunnel operations:

  • remote datasource tunnels show reconnect counts and last-failure diagnostics in the web admin
  • dead tunnels can be reconnected directly from the diagnostics page

Contribution and release notes:

Linux Scope

This project is currently Linux-first. The repository includes first-class packaging for Arch-like systems, including CachyOS.

License

MIT. See LICENSE.

Metadata

Release files for cockpit-cli 0.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cockpit-cli 0.1.3
File Size Uploaded Provenance Actions
cockpit_cli-0.1.3.tar.gz 372.1 kB Without provenance Details for cockpit_cli-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cockpit-cli 0.1.3
File Interpreter ABI Platform Actions
cockpit_cli-0.1.3-py3-none-any.whl Python 3 none any Details for cockpit_cli-0.1.3-py3-none-any.whl

Total release size: 746.3 kB

Release files / cockpit_cli-0.1.3.tar.gz

Download URL cockpit_cli-0.1.3.tar.gz
Size 372.1 kB
Tags Source
SHA-256 checksum
How to use checksums
3b673e970586d37db7924bd370d24b934a9b5b19e667fdf3d7e1d83bb6899cb9
BLAKE2b-256 checksum
How to use checksums
f5f4b9d1bf99c131097db23eeba6973f851d96028087de8470c2845c6060dca5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.3

Release files / cockpit_cli-0.1.3-py3-none-any.whl

Download URL cockpit_cli-0.1.3-py3-none-any.whl
Size 374.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c6e1d1e0a6032fe6647c29fb42396c556b5df7bc71e18d328ef37d84da29382d
BLAKE2b-256 checksum
How to use checksums
166507ff36a76a46c97e749c4e297aec2ded70264bf5099a97a99221c2ba49d1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.3

Security for cockpit-cli 0.1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.3 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page