Skip to content

07 Browsing and Searching Packages

After packages are published, operators and developers need fast discovery. Athene provides two complementary views: path-style browsing (ls/list) and index-style package queries (list-packages/find).

7.1 Prerequisites

  • At least one repository containing imported packages.
  • Read access for your CLI credentials.
  • Athene CLI available in your shell as athene.

7.2 Quick Start

Step 1: Browse repository roots

athene ls
athene ls debian/main

Step 2: Use long listing for metadata

athene ls /r/debian/main -l

Step 3: Query indexed packages

athene debian list-packages
athene debian list-packages main
athene debian list-packages main wombat.security

Step 4: Use interactive search when triaging

athene find
athene find debian main
athene find debian main wombat.security

7.3 Key Parameters Explained

  • ls path: reads raw repository tree under /r and is ideal for storage-path debugging.
  • -l or --long: adds metadata (type size lastModified name) for forensic checks.
  • list-packages <repo> <search>: queries Athene index and is usually the fastest way to locate a package version.
  • find <type> <repository> <search>: interactive TUI for narrowing large result sets quickly.

Tip

Use list-packages for package identity questions and ls for layout questions. Mixing both views deliberately helps you isolate whether a problem is indexing, naming, or path-level storage.

7.4 Other Ways to Browse and Search Repositories

7.5 Pinning Tags to Versions

Pinning lets you attach stable names (tags) to specific package versions so consumers can use durable URLs while you control rollout timing.

Typical uses:

  • Keep stable fixed on a known-good version while testing newer builds.
  • Move beta forward for pre-release users without changing production consumers.
  • Use current as an automatically managed pointer to the newest semantic version.

Pin, inspect, and unpin from CLI

athene files pin binaries --namespace com.acme demo stable 1.2.3
athene files pins binaries --namespace com.acme demo
athene files unpin binaries --namespace com.acme demo stable

Resolve tags through package and repository URLs

curl -X GET "http://localhost:19191/p/files/binaries/com/acme/demo/stable"
curl -X GET "http://localhost:19191/r/files/binaries/com/acme/demo/current/ALL/ALL/demo.mcpb"

Permissions and behavior

  • Users with read access can list pins and resolve tags.
  • Users with write access can pin and unpin tags.
  • current is immutable and cannot be manually pinned or unpinned.

7.6 Next Steps

Now is a good time to secure your created repositories and prepare your server for real-world users.

Next chapter: 08 User and Access Control.