libra mega2
Command reference for Libra's Mega2 traces and browser commands
libra mega2 traces reads scoped agent history and can fetch one verified stream.
libra mega2 traces capabilities --server <BASE-URL> [--token-file <PATH> | --token <TOKEN>] [--require-search]
libra mega2 traces targets --server <BASE-URL> --path </project/foo> [--token-file <PATH> | --token <TOKEN>]
libra mega2 traces streams --server <BASE-URL> --target <UUID> [--source <ID>] [--owner <UUID>] [--epoch <UUID>] [--cursor <CURSOR>] [--limit <N>] [--token-file <PATH> | --token <TOKEN>]
libra mega2 traces sessions --server <BASE-URL> --stream <UUID> [--since <RFC3339>] [--until <RFC3339>] [--agent <KIND>] [--code-commit <OID>] [--session <ID>] [--cursor <CURSOR>] [--limit <N>] [--token-file <PATH> | --token <TOKEN>]
libra mega2 traces show --server <BASE-URL> --stream <UUID> (--session <ID> | --checkpoint <ID>) [--token-file <PATH> | --token <TOKEN>]
libra mega2 traces checkpoints --server <BASE-URL> --stream <UUID> --session <ID> [--cursor <CURSOR>] [--limit <N>] [--token-file <PATH> | --token <TOKEN>]
libra mega2 traces search --server <BASE-URL> --target </project/foo> --stream <UUID> --query <TEXT> [--cursor <CURSOR>] [--limit <N>] [--max-bytes <BYTES>] [--token-file <PATH> | --token <TOKEN>]
libra mega2 traces transcript --server <BASE-URL> --stream <UUID> [--session <ID>] --checkpoint <ID> [--max-bytes <BYTES>] [--cursor <CURSOR>] [--token-file <PATH> | --token <TOKEN>]
libra mega2 traces fetch --remote <NAME> --stream <UUID> [--token-file <PATH> | --token <TOKEN>]
HTTP read commands accept an optional bearer token. HTTP(S) traces fetch
requires a token and authenticates with HTTP Basic using username traces and
the token as its password. Token sources are checked in this order:
--token-file <PATH>, LIBRA_MEGA2_TOKEN, then --token <TOKEN>. An inline
token can appear in shell history and process listings; prefer
--token-file. SSH traces fetch authenticates with the configured
traces@ key and does not send a token.
Search text must be 1 to 256 UTF-8 bytes or the command does not open a socket.
The client sends the query unchanged; ASCII case-fold is the server's match.
Search calls the mounted per-stream route
/api/v1/traces/streams/<UUID>/search, so --stream is required; --target
is still accepted for compatibility, and --source, --session, --agent,
--since, --until and --code-commit are refused locally because that
route does not implement them. The route owns the transcript-body budget, so
--max-bytes is validated locally (default 16384, maximum 131072 bytes) but is
not sent. Transcript resolves the owning session when --session is omitted by
paging the stream's sessions and checkpoints. List --limit defaults to 50 and
accepts at most 200; search --limit defaults to 20 hits and accepts at most
100. Transcript --max-bytes defaults to 16384 and accepts at most 131072
bytes. Values above the relevant maximum are rejected before a socket opens.
--owner, --epoch, --agent, --session, and --cursor are passed through
as written where the mounted route supports them.
--code-commit must be 40 or 64 hexadecimal characters. --since and
--until are RFC3339 values sent as UTC on the half-open interval
[since, until); since later than until is rejected locally, and equal
bounds are an empty interval. For show, --session and --checkpoint cannot
be combined.
--require-search succeeds only when search_ready is boolean true; a
missing or non-boolean field is rejected, while a plain capabilities call
still prints the other fields. A redirect to another origin does not forward
Authorization. Traces JSON API responses over 1 MiB are rejected. The Git
pack fetched by traces fetch has a separate 512 MiB limit. Fetch reads one
stream with Git upload-pack from /.traces/by-scope/<stream>.git on the origin
of remote.<name>.url. It takes server_id from the authenticated
advertisement, verifies and indexes the received pack, and writes
refs/remotes/<remote>/traces/<stream>/<sha1|sha256> only when the advertised
tip is a commit in that pack and the hash kind matches the repository object
format. It records the server fingerprint and refuses a silent remote retarget.
It does not update refs/heads/traces, refs/libra/traces, HEAD, the index,
or the worktree. An unknown or unauthorized stream returns unknown_scope and
publishes nothing.
# For an HTTP(S) remote; SSH fetch uses the configured traces@ key instead.
libra mega2 traces fetch --remote origin --stream 3f1d2c4b-5a6e-4f70-8a9b-0c1d2e3f4a5b --token-file ~/.mega2-token
libra mega2 browser
Browse a remote Mega2 repository over HTTP with a directory tree on the left
and file content on the right. Scripts and agents can still request a single
directory-level listing with --list, --json or --machine.
mega2 is a Libra-only extension. It has no Git-equivalent contract:
mega2 browser never clones, fetches, or pushes Git objects. It lists remote
metadata and file previews rather than local tree objects. For local object inspection use
libra ls-tree.
Synopsis
libra mega2 browser --server <BASE-URL> [PATH] [--ref <COMMIT-OR-TAG>] [--json|--machine]
libra mega2 browser --server <BASE-URL> [PATH] [--ref <COMMIT-OR-TAG>] --list [--json|--machine]
Description
The command validates every input before touching the terminal or the network:
--servermust behttps://…, orhttp://…only when the host is loopback (127.0.0.1,::1,localhost). Credentials (userinfo), query strings, fragments and a base path are rejected; the client always appends the fixed/api/v1/treeand/api/v1/blobread routes.PATHmust be rooted (/by default) and may not contain./..components, NUL, control characters or platform separators.--refselects a commit or tag to list; when omitted the server's default revision is used.
Expanding or reloading a directory sends one anonymous GET /api/v1/tree.
Selecting a file sends one anonymous GET /api/v1/blob?path=…&refs=… (the refs
parameter is omitted without --ref). Moving among directories, collapsing
branches, and scrolling already loaded content are local operations.
No Authorization header is attached to either read route, no repository is opened (the
command works outside a repository), and no local state — index, object store,
database, configuration — is read or written.
The client is bounded: it disables redirects and proxies, applies a 10-second
timeout, caps the response body at 1 MiB and the listing at 2000 entries, and
accepts only entries whose content_type is directory or file. Names with
.., path separators or terminal control characters are refused
fail-closed, and the server-provided item path is never used as navigation
authority.
Revision warning:
--refselects the revision for browsing and reads only. Current interactive create/delete/move/rename actions still target the server default revision, not the selected commit/tag. Treat--refbrowsing as read-only and do not confirm interactive writes there; the behavior fix is deferred. Non-interactive write flags combined with--refremain rejected before any request.
Interactive mode (default)
Interactive mode requires stdin and stdout to be terminals. If either is
not a TTY the command refuses immediately with a stable error and a hint to use
--json; it never alters the terminal.
While browsing, the terminal is switched to raw mode and driven by a bounded
state machine with lazy expansion and no recursive/background prefetch. The
left pane retains expanded branches and their siblings. Selecting a file loads
its text in the right pane, with line numbers and independent scrolling.
Loading, empty, missing, binary/unsupported, and oversized files have explicit
messages; a failed preview does not exit the browser or display the previous
file. The server must support UTF-8 text via /api/v1/blob. Preview text is
limited to 256 KiB, with a 1 MiB wire-response cap and a 10-second deadline;
no preview is saved locally. Tabs display as four spaces, terminal control and
bidirectional-control characters are neutralized. The expanded tree is capped
at 8192 rows, 4 MiB of stored path/name bytes and 128 child levels; collapse a
branch to free space. Unix terminals redraw on resize; below 49 columns by 10
rows the UI shows a resize hint.
File previews detect syntax from the filename/extension (or a script's shebang).
Rust, Python, JavaScript, C/C++, shell, JSON, YAML, Markdown, HTML/CSS and
TOML/INI configuration files are highlighted; .buckconfig, .gitconfig,
.editorconfig and BUCK/BUILD also have filename rules. Keywords, strings,
numbers, names and comments use the terminal's own color palette. The content
header identifies the detected syntax. Unknown types stay plain text.
--no-color, --color=never and automatic NO_COLOR/TERM=dumb handling disable
syntax colors; explicit --color=always overrides the automatic environment
policy. Only interactive previews are colored: machine/list output is unchanged.
Highlighting is cached per file and does not make extra requests. Text larger
than 64 KiB after display normalization, lines over 4096 bytes, or exhausted
highlighting work limits fall back to plain text with a header note; the 256 KiB
text-preview limit still applies. Multiline syntax remains correct while scrolling.
| Key | Action |
|---|---|
↑/↓ or k/j |
Move the tree selection; in the content pane, scroll lines |
Enter |
Expand/fold a directory; on a file, focus its content |
→ |
Expand a directory or select its first child; in content, scroll right |
←, Backspace or h |
Fold a branch or select its parent; at a subtree root, load its parent (never above /); content ← scrolls left |
Tab |
Switch focus between directory tree and file content |
PageUp / PageDown |
Scroll file content one screen |
a |
Create a child inside the selected directory (see below) |
d |
Delete the selected directory (confirmation dialog; files are inert) |
m |
Move the selected file or directory with a destination-folder picker |
e |
Rename the selected directory (same parent; r still reloads) |
t |
Toggle the tag panel (see below) |
r |
Reload the selected directory or file; from an empty tree, reload its root |
q (or Ctrl-C, Esc) |
Quit |
The primary shortcuts use single keys without Shift. a also creates a tag
inside the tag panel; legacy + (create) and R (rename) remain aliases.
While entering a name or tag message, printable shortcut characters are literal
text (including q); Enter submits, Backspace edits and Esc cancels. Directory
names and tag names/messages use centered popup dialogs with a labeled input
and visible cursor. Long input scrolls to its end; validation errors appear
inside the dialog. Delete confirmations also use a popup. Moving uses a separate
folder picker: Right enters a destination folder, Enter chooses it, and a
second Enter confirms the write. Dialogs fit terminals down to 49 × 10, work
without color, and preserve
the underlying tree/tag selection when cancelled.
Terminal state (raw mode and the alternate screen) is restored on every exit
path, including errors and signals handled by the process.
Directory mutation shortcuts apply only while the tree has focus. a creates
inside the selected directory, whether expanded or folded, and refreshes that
directory's children. Delete and rename operate on the selected directory;
move operates on the selected file or directory, using its actual parent even
for nested rows, and refreshes that parent branch. A cross-parent move from a
nested branch also reloads the visible root and folds its branches, avoiding
stale destination entries. JSON/machine schemas and their one-request behavior
are unchanged.
Machine mode (--json / --machine)
With --json (or --machine, which implies --json=ndjson --no-pager --color=never --quiet) and no operation flag, the command lists PATH exactly
like --list (see Non-interactive operations):
one fetch, printed as the standard Libra JSON envelope:
{
"ok": true,
"command": "mega2 browser",
"data": {
"operation": "list",
"server": "https://mega2.example.com",
"ref": "v1.2",
"path": "/src",
"items": [
{ "name": "pkg", "content_type": "directory" },
{ "name": "main.rs", "content_type": "file" }
]
}
}
items is deterministic: directories first, then names in ascending order.
server is the canonical scheme/host/port origin of the validated URL.
--quiet without a machine output mode or an operation flag is rejected:
suppressing stdout would break interactive rendering. With an operation flag,
--quiet suppresses the plain-text summary.
Non-interactive operations
Browser functions also have non-interactive forms for scripts, CI and
black-box tests: each is one operation flag on the same mega2 browser
command, and at most one operation flag is accepted per call. The table lists
the forms available in this release.
| Interactive key | Flag | Request |
|---|---|---|
| start, expand/reload a directory, load a parent root | --list (PATH is the directory; --json without a flag is the same) |
GET /api/v1/tree |
a |
--create-dir <NAME> (PATH is the parent) |
POST /api/v1/create-entry |
d |
--delete-dir <NAME> (PATH is the parent) |
POST /api/v1/delete-entry |
m |
--move-dir <NAME> <PARENT-PATH> (directory only; PATH is NAME's current parent; the name is kept) |
POST /api/v1/move-entry |
e |
--rename-dir <NAME> <NEW-NAME> (PATH is the parent, which is kept) |
POST /api/v1/move-entry |
t, then n/p |
--list-tags [--page <N>] [--per-page <N>] (PATH must be /) |
GET /api/v1/tags/list |
t, then a |
--create-tag <NAME> [--message <TEXT>] (PATH must be /) |
POST /api/v1/tags |
t, then d |
--delete-tag <NAME> (PATH must be /) |
DELETE /api/v1/tags/{name} |
Every non-interactive call follows the same rules:
- No terminal, no input. It runs with stdin closed or redirected and stdout/stderr piped; it never reads stdin, never prompts and never changes terminal state.
- One request. Input is validated locally first; a call that passes sends exactly one HTTP request and a call that fails validation sends none. There is no reload, preflight or retry.
- Output. On success stdout holds only the JSON envelope (
--json,--machine) or a plain-text summary with control characters replaced (nothing with--quiet). On failure stdout is empty and the error goes to stderr: the JSON error envelope with--json/--machine(see Machine error details), the human error otherwise. - Credentials. Read operations refuse token flags: they are anonymous,
reject
--tokenand--token-file(LBR-CLI-002, no request) and ignoreLIBRA_MEGA2_TOKEN. Write operations, in human and machine mode alike, take at most one token —--token-file, thenLIBRA_MEGA2_TOKEN, then--token— and send it as oneAuthorization: Bearerheader; with no source they write anonymously (forpush_auth=noneservers). The token is never persisted or printed, not even when the server rejects it. - One operation, no
--refon writes. Combining two operation flags is a usage error (LBR-CLI-002), and so is--refwith a write operation: writes always target the server's default revision. Neither sends a request. - Tags: root only, no revision. Tag operations act on root tags: PATH
must be
/(the default), and--refis refused. Both fail withLBR-CLI-002before any request. - Writes are not retried. A write whose outcome is unknown is never
repeated by Libra. That happens when it times out or fails before any
response (
LBR-NET-001withdetails.transporttimeoutorrequest), when the connection drops while the receipt is read (LBR-NET-001withdetails.http_status), or when a2xxcarries an invalid receipt (LBR-NET-002with a2xxdetails.http_status). Check the result before repeating the call: with--listafter a directory write; after a tag write, with--list-tags, paging untilhas_nextisfalse— an annotated tag appears on one of the pages, but a lightweight tag can be missing from all of them (see the paging note under--list-tags).details.transportconnectmeans the request never reached the server. - Exit codes.
0on success; on failure the stable code's exit code (129for usage errors such asLBR-CLI-002andLBR-CLI-003,128otherwise), or the category code (2–9) whenLIBRA_FINE_EXIT_CODES=1.
--list prints one line per entry, directories first, as dir <name> or
file <name>; with --json/--machine it prints the payload shown above.
--create-dir <NAME> creates directory NAME under PATH with one
POST /api/v1/create-entry and does not reload. The plain-text summary is
created directory <path> (commit <commit_id>); with --json/--machine the
payload separates what was asked from what the server answered:
{
"operation": "create-dir",
"server": "https://mega2.example.com",
"target": { "parent": "/src", "name": "pkg", "path": "/src/pkg" },
"receipt": { "commit_id": "…", "new_oid": "…", "path": "/src/pkg", "cl_link": null }
}
target is built from your validated input; receipt is the server's
receipt verbatim (path and cl_link may be null). Errors:
| Situation | Stable code | details |
|---|---|---|
NAME is ./.., empty, too long, or has a separator or control character |
LBR-CLI-002 |
none (no request) |
Combined with another operation flag or with --ref |
LBR-CLI-002 |
none (no request) |
| The directory already exists (mega2 answers HTTP 500 today) | LBR-NET-002 |
http_status: 500 |
| HTTP 400 (rejected name or parent) | LBR-CLI-003 |
http_status: 400 |
| HTTP 401 (server needs a write token) / 403 (token not allowed here) | LBR-AUTH-001 / LBR-AUTH-002 |
http_status |
| HTTP 409 | LBR-CONFLICT-002 |
http_status: 409 |
| Other non-2xx, or a 2xx whose receipt is invalid | LBR-NET-002 |
http_status |
| Timeout or connection failure before any response | LBR-NET-001 |
transport |
| Connection drops while the receipt is read (outcome unknown) | LBR-NET-001 |
http_status |
--delete-dir <NAME> deletes directory NAME under PATH with one
POST /api/v1/delete-entry and does not reload. There is no confirmation
line: the flag names the exact target. The plain-text summary is
deleted directory <path> (commit <commit_id>); with --json/--machine the
payload is:
{
"operation": "delete-dir",
"server": "https://mega2.example.com",
"target": { "parent": "/src", "name": "pkg", "path": "/src/pkg" },
"receipt": { "commit_id": "…", "path": "/src/pkg", "cl_link": null }
}
Libra does not check beforehand whether NAME exists or is a directory: the
server answers both. A file target is LBR-CLI-003; a missing target is
LBR-NET-002 today, told apart from other failures by details.http_status.
Errors:
| Situation | Stable code | details |
|---|---|---|
NAME is ./.., empty, too long, or has a separator or control character |
LBR-CLI-002 |
none (no request) |
Combined with another operation flag or with --ref |
LBR-CLI-002 |
none (no request) |
| HTTP 400: NAME is a file, PATH runs through a file, or the server refuses the path (for example a top-level directory on a trunk server) | LBR-CLI-003 |
http_status: 400 |
| NAME, or PATH itself, does not exist (HTTP 404) | LBR-NET-002 |
http_status: 404 |
| HTTP 401 / 403 / 409, other failures, unknown outcomes | as for --create-dir |
as for --create-dir |
--move-dir <NAME> <PARENT-PATH> moves directory NAME from PATH into the
existing directory PARENT-PATH, keeping its name, with one
POST /api/v1/move-entry, and does not reload. PARENT-PATH is validated like
PATH before the request. The plain-text summary is
moved directory <from> -> <to> (commit <commit_id>); with --json/--machine
the payload is:
{
"operation": "move-dir",
"server": "https://mega2.example.com",
"target": {
"from": { "parent": "/src", "name": "pkg", "path": "/src/pkg" },
"to": { "parent": "/lib", "name": "pkg", "path": "/lib/pkg" }
},
"receipt": { "commit_id": "…", "from_path": "/src/pkg", "to_path": "/lib/pkg", "cl_link": null }
}
As with --delete-dir, the server answers whether the move is possible.
Errors:
| Situation | Stable code | details |
|---|---|---|
NAME is ./.., empty, too long, or has a separator or control character |
LBR-CLI-002 |
none (no request) |
PARENT-PATH is not rooted, or has ./.. components, a \ or a control character |
LBR-CLI-003 |
none (no request) |
Combined with another operation flag or with --ref |
LBR-CLI-002 |
none (no request) |
| HTTP 400: PARENT-PATH already has an entry named NAME, PARENT-PATH is PATH itself or lies inside NAME, NAME is a file, PATH or PARENT-PATH runs through a file, or the server refuses the path (for example, on a trunk server, a move between two top-level directories) | LBR-CLI-003 |
http_status: 400 |
| HTTP 404: NAME, PATH or PARENT-PATH does not exist | LBR-NET-002 |
http_status: 404 |
| HTTP 401 / 403 / 409, other failures, unknown outcomes | as for --create-dir |
as for --create-dir |
--rename-dir <NAME> <NEW-NAME> renames directory NAME under PATH to NEW-NAME
with one same-parent POST /api/v1/move-entry, and does not reload. The
plain-text summary is renamed directory <from> -> <to> (commit <commit_id>);
with --json/--machine the payload has the --move-dir shape, with
target.to.parent equal to target.from.parent:
{
"operation": "rename-dir",
"server": "https://mega2.example.com",
"target": {
"from": { "parent": "/src", "name": "old", "path": "/src/old" },
"to": { "parent": "/src", "name": "new", "path": "/src/new" }
},
"receipt": { "commit_id": "…", "from_path": "/src/old", "to_path": "/src/new", "cl_link": null }
}
Errors:
| Situation | Stable code | details |
|---|---|---|
NAME or NEW-NAME is ./.., empty, too long, or has a separator or control character |
LBR-CLI-002 |
none (no request) |
Combined with another operation flag or with --ref |
LBR-CLI-002 |
none (no request) |
| HTTP 400: NEW-NAME equals NAME, PATH already has an entry named NEW-NAME, NAME is a file, PATH runs through a file, or the server refuses the path (for example a top-level directory on a trunk server) | LBR-CLI-003 |
http_status: 400 |
| HTTP 404: NAME or PATH does not exist | LBR-NET-002 |
http_status: 404 |
| HTTP 401 / 403 / 409, other failures, unknown outcomes | as for --create-dir |
as for --create-dir |
--list-tags lists one page of root tags with one anonymous
GET /api/v1/tags/list (query page, per_page and path=/). --page
(1–1000, default 1) and --per-page (1–100, default 20, the interactive
panel's page size) choose the page; both are refused without --list-tags.
Each tag prints as <name> <object_type> <tagger>, followed by its message
on a line indented by four spaces when it has one, then a
page <page> · per_page <per_page> · total <total> line; control characters
in server strings print as ?. With --json/--machine the payload is:
{
"operation": "list-tags",
"server": "https://mega2.example.com",
"path": "/",
"page": 1,
"per_page": 20,
"total": 42,
"has_next": true,
"items": [
{ "name": "v1.0", "tag_id": "…", "object_id": "…", "object_type": "commit",
"tagger": "…", "message": "…", "created_at": "…" }
]
}
has_next is page * per_page < total; items keep every server field
verbatim. mega2 today pages annotated tags in its database, then fills the
rest of the page from its refs/tags/* refs, always starting again from the
first ref and skipping only the annotated tags already on that page. Annotated
tags have refs too, so a page can repeat tags from other pages; such entries,
like lightweight tags, carry ref-only fields (object_type commit, empty
tagger and message, tag_id equal to object_id). total adds every
such ref to the annotated count, so it can exceed the number of distinct tags
and differ from page to page, and has_next inherits that. Errors:
| Situation | Stable code | details |
|---|---|---|
--page outside 1–1000 or --per-page outside 1–100 |
LBR-CLI-002 |
none (no request) |
--page or --per-page without --list-tags |
LBR-CLI-002 |
none (no request) |
A malformed PATH (not rooted, or with ./.. components) |
LBR-CLI-003 |
none (no request) |
A rooted PATH other than /, --ref, a token flag, or another operation flag |
LBR-CLI-002 |
none (no request) |
| HTTP, transport or response failures | the failure's stable code (see Machine error details) | http_status or transport |
--create-tag <NAME> creates root tag NAME with one POST /api/v1/tags
(path_context /). Without --message the tag is lightweight;
--message <TEXT> makes it annotated. Unlike the interactive panel, where an
empty message means lightweight, a non-interactive --message must be
non-empty, at most 1024 bytes and free of control characters, newlines
included: it is refused, never rewritten. A root tag needs a write token whose
paths cover /, or a push_auth=none server; a token limited to other paths
gets HTTP 403 (LBR-AUTH-002). The plain-text summary is
created <kind> tag <name> -> <object_id>; with --json/--machine the
payload is:
{
"operation": "create-tag",
"server": "https://mega2.example.com",
"target": { "name": "v1.0", "kind": "annotated", "path": "/" },
"receipt": { "name": "v1.0", "tag_id": "…", "object_id": "…", "object_type": "commit",
"tagger": "…", "message": "…", "created_at": "…" }
}
target.kind is lightweight or annotated; receipt is the server's tag
verbatim. Errors:
| Situation | Stable code | details |
|---|---|---|
| NAME breaks the tag-name rules (see the tag panel) | LBR-CLI-002 |
none (no request) |
--message empty, over 1024 bytes or with a control character, or given without --create-tag |
LBR-CLI-002 |
none (no request) |
A malformed PATH (not rooted, or with ./.. components) |
LBR-CLI-003 |
none (no request) |
A rooted PATH other than /, --ref, or another operation flag |
LBR-CLI-002 |
none (no request) |
| HTTP 400 (for example, the tag already exists), 405 or 422 | LBR-CLI-002 |
http_status |
HTTP 401 (server needs a write token) / 403 (the token does not cover /) |
LBR-AUTH-001 / LBR-AUTH-002 |
http_status |
| HTTP 404 / 409 | LBR-CLI-003 / LBR-CONFLICT-002 |
http_status |
| Any other non-2xx or an invalid receipt / a timeout or dropped connection | LBR-NET-002 / LBR-NET-001, as for --create-dir |
http_status or transport |
--delete-tag <NAME> deletes root tag NAME with one
DELETE /api/v1/tags/{name}?path=/ (NAME percent-encoded), with no
confirmation line and no reload. Like creating one, deleting a root tag needs
a write token whose paths cover /, or a push_auth=none server. The
plain-text summary is deleted tag <name>; with --json/--machine the
payload is:
{
"operation": "delete-tag",
"server": "https://mega2.example.com",
"target": { "name": "v1.0", "path": "/" },
"receipt": { "deleted_tag": "v1.0", "message": "…" }
}
Errors:
| Situation | Stable code | details |
|---|---|---|
| NAME breaks the tag-name rules (see the tag panel) | LBR-CLI-002 |
none (no request) |
A malformed PATH (not rooted, or with ./.. components) |
LBR-CLI-003 |
none (no request) |
A rooted PATH other than /, --ref, or another operation flag |
LBR-CLI-002 |
none (no request) |
| The tag does not exist (HTTP 404) | LBR-CLI-003 |
http_status: 404 |
HTTP 401 (server needs a write token) / 403 (the token does not cover /) |
LBR-AUTH-001 / LBR-AUTH-002 |
http_status |
| HTTP 400, 405 or 422 / 409 | LBR-CLI-002 / LBR-CONFLICT-002 |
http_status |
| Any other non-2xx or an invalid receipt / a timeout or dropped connection | LBR-NET-002 / LBR-NET-001, as for --create-dir |
http_status or transport |
Creating a directory (a, interactive only)
Press a to open a centered name dialog for a child of the selected
directory (or of the visible root when the tree is empty). The dialog shows the
parent path: selecting /artifact and entering rust creates /artifact/rust,
not /rust. The selected directory need not be expanded. While a file is
selected the editor refuses to open — selection must be a directory or an
empty area. Enter validates the name with the same rules used for the wire
(/, \, ., .., NUL and control characters are refused) and only then
performs one POST /api/v1/create-entry with is_directory=true,
skip_build=true and no content; Esc cancels with no network at all.
A confirmed creation reloads the target directory exactly once and shows its children. Failures (401/403, duplicate name, timeout, malformed response) keep the last safe listing on screen and show a secret-free status line; the terminal is never left in raw mode and the TUI never asks you to type a raw token on the alternate screen.
HTTP 400 does not necessarily mean the name already exists: check the parent
path, the server's path policy and the name. Mega2 deployments restrict new
paths to configured monorepo roots; selecting /artifact creates beneath that
root without attempting a new top-level path. Raw server error bodies are not
displayed, to avoid leaking secrets.
Write tokens are read, in order of precedence, from --token-file <path>,
then the LIBRA_MEGA2_TOKEN environment variable, then --token (visible in
shell history — prefer the first two). The same rule applies to the
non-interactive write operations (see above). Read operations refuse token
flags: --json/--machine without a write flag and --list take no
credentials.
Deleting, moving and renaming (d, m, e, interactive only)
d opens a confirmation dialog before deleting the selected directory; m
opens a destination-folder picker for the selected file or directory; e
renames a selected directory in place (the same-parent form of the move
operation). The picker fixes the source before browsing: Right enters a
folder, the first Enter chooses it, and the second Enter performs the
move. Esc returns from confirmation to the picker, then cancels without a
write request. Files stay inert for delete and rename only.
Mega2 trunk writes cannot land on /; therefore a move cannot cross top-level
monorepo roots. For example, /artifact/rust cannot move to /data. The
picker only shows destinations below the source root (for example,
/artifact), so that impossible request is never sent. It also refuses a
directory's own descendants before the POST.
Each confirmed mutation performs one POST /api/v1/delete-entry or
POST /api/v1/move-entry followed by one parent-branch listing reload.
A cross-parent move from a nested branch adds one root reload and folds the tree.
Success clears
the status; failures (401/403, missing source, duplicate destination,
timeout) keep the last safe listing and show a secret-free status line while
the terminal stays intact. There is no multi-select and no recursion: one
selected entry per operation (a directory for delete/rename, or a file or
directory for move).
Tag panel (t, interactive only)
t opens the tag panel and performs exactly one anonymous
GET /api/v1/tags/list for page 1 (the three required query keys are
page, per_page, path; this MVP always uses the repository root
path=/). n/p request the explicit next/previous page — one request per
key, never prefetched. a collects a tag name and then an optional message
(an empty message creates a lightweight tag; a non-empty one creates an
annotated tag); d deletes the selected tag after a confirmation
dialog. t, Esc or q close the panel without leaving the browser, and the
directory listing reappears unchanged.
Tag names are validated with the server's rules before any request (non-empty,
at most 255 bytes, no .., @{, //, no .lock suffix and no
whitespace/control/forbidden characters). Listing is anonymous; create and
delete reuse the session write token from ADR-MB-03. Rendered tag fields
(tagger, message) are sanitized so hostile server strings cannot control the
terminal. The panel operates root tags only.
Options
| Option | Description |
|---|---|
--server <BASE-URL> |
Mega2 server base URL (required). HTTPS, or loopback HTTP. |
[PATH] |
Rooted directory to list, or the parent for a directory write; defaults to /. Tag operations accept only /. |
--ref <COMMIT-OR-TAG> |
Optional commit or tag to list. |
--list |
List PATH once without a terminal: plain-text lines, or the JSON payload with --json/--machine. |
--create-dir <NAME> |
Create directory NAME under PATH without a terminal (one POST, no reload). |
--delete-dir <NAME> |
Delete directory NAME under PATH without a terminal (one POST, no confirmation, no reload). |
--move-dir <NAME> <PARENT-PATH> |
Move directory NAME from PATH into PARENT-PATH, keeping its name, without a terminal (one POST, no reload). |
--rename-dir <NAME> <NEW-NAME> |
Rename directory NAME under PATH to NEW-NAME, keeping its parent, without a terminal (one POST, no reload). |
--list-tags |
List one page of root tags without a terminal (one GET). |
--page <N> |
With --list-tags: the page to list (1–1000; default 1). |
--per-page <N> |
With --list-tags: tags per page (1–100; default 20). |
--create-tag <NAME> |
Create root tag NAME without a terminal (one POST): lightweight, or annotated with --message. |
--message <TEXT> |
With --create-tag: the annotated tag's message (non-empty, at most 1024 bytes, no control characters). |
--delete-tag <NAME> |
Delete root tag NAME without a terminal (one DELETE, no confirmation). |
--token-file <PATH> |
Write operations (interactive or non-interactive): read the write token from a file (highest precedence). Refused by read operations. |
--token <TOKEN> |
Write operations: inline write token (lowest precedence; visible in shell history — prefer --token-file). Refused by read operations. |
--json[=<FORMAT>] |
Global flag: one request, JSON envelope (pretty/compact/ndjson). |
--machine |
Global flag: strict NDJSON machine mode for automation. |
Errors
| Situation | Stable behavior |
|---|---|
Invalid invocation (bad URL, unrooted path, missing --server) |
Usage error, no request |
| Interactive mode without a TTY | Refused before any terminal change or request; hint to use --json |
| Network unavailable / timeout | Stable network error, no response body echoed |
| HTTP 4xx/5xx or a redirect | Stable error naming the status; the body is never printed |
| Malformed or hostile server response | Stable protocol error; nothing is rendered or cached |
Errors never echo server response bodies, credentials, tokens or unvalidated paths.
Machine error details
Every failed Mega2 request adds details to the JSON error envelope (on stderr
with --json/--machine, and on the trailing JSON line when stderr is not a
terminal). The stable code and message stay as listed above; details lets
automation tell HTTP statuses apart without parsing the message:
| Key | Meaning |
|---|---|
method |
GET, POST or DELETE |
route |
Route template, for example /api/v1/tree or /api/v1/tags/{name} |
http_status |
Status received — also for a 2xx whose body is invalid, or a connection that drops while the body is read |
transport |
timeout, connect or request when no status was received |
{"ok":false,"error_code":"LBR-NET-002","category":"network","exit_code":128,"severity":"fatal","message":"mega2 server returned HTTP 500 Internal Server Error","details":{"http_status":500,"method":"GET","route":"/api/v1/tree"}}
Invalid input rejected before any request carries no details. The values
never include the response body, the server URL or a token; see
error codes.
Limits and boundaries
- One request per directory expansion/reload or file selection; moving between directory rows and collapsing branches sends none. No recursive prefetch, background task, or cache that outlives the process.
- Browse is read-only and anonymous. A confirmed
aadds at most onecreate-entryPOST plus one reload GET;d/m/elikewise add onedelete-entry/move-entryPOST plus one parent reload GET (a cross-parent move from a nested branch adds one root reload). No recursive or multi-selection operation exists in this command. - No configuration or credential persistence: nothing written to disk.
Examples
# Browse the remote root interactively
libra mega2 browser --server https://mega2.example.com
# Open a rooted path directly
libra mega2 browser --server https://mega2.example.com /src/pkg
# Plain-text listing without a terminal (scripts, CI)
libra mega2 browser --server https://mega2.example.com --list /src/pkg
# Create /src/pkg without a terminal (anonymous write, push_auth=none servers)
libra --json mega2 browser --server https://mega2.example.com --create-dir pkg /src
# The same write with a token from a file (token-protected servers)
libra --json mega2 browser --server https://mega2.example.com --create-dir pkg /src --token-file ~/.mega2-token
# Delete /src/pkg without a terminal (no confirmation: the flag names the target)
libra --json mega2 browser --server https://mega2.example.com --delete-dir pkg /src --token-file ~/.mega2-token
# Move /src/pkg to /src/archive/pkg without a terminal
libra --json mega2 browser --server https://mega2.example.com --move-dir pkg /src/archive /src --token-file ~/.mega2-token
# Rename /src/old to /src/new without a terminal
libra --json mega2 browser --server https://mega2.example.com --rename-dir old new /src --token-file ~/.mega2-token
# Second page of root tags, 50 per page, as JSON
libra --json mega2 browser --server https://mega2.example.com --list-tags --page 2 --per-page 50
# Create annotated root tag v1.0 without a terminal
libra --json mega2 browser --server https://mega2.example.com --create-tag v1.0 --message "release 1.0" --token-file ~/.mega2-token
# Delete root tag v1.0 without a terminal (no confirmation)
libra --json mega2 browser --server https://mega2.example.com --delete-tag v1.0 --token-file ~/.mega2-token
# List a specific commit or tag
libra mega2 browser --server https://mega2.example.com --ref v1.2
# Create/delete/rename directories or move a file/directory interactively (press a, d, m or e; t for tags)
libra mega2 browser --server https://mega2.example.com --token-file ~/.mega2-token
# Exactly one fetch, JSON envelope (works without a TTY, outside any repository)
libra --json mega2 browser --server https://mega2.example.com
# NDJSON for automation
libra --machine mega2 browser --server http://127.0.0.1:8080
Comparison with libra ls-tree
| Aspect | libra mega2 browser |
libra ls-tree |
|---|---|---|
| Data source | Remote Mega2 HTTP API (/api/v1/tree) |
Local object database |
| Requires a repository | No | Yes |
| Depth | Exactly one directory level per fetch | Arbitrary tree paths (-r for recursion) |
| Auth | Anonymous (no token) | Local repository access |
| Git compatibility | None (Libra-only extension) | Git-compatible plumbing |