Reference · command

metais ls

List the entries under a path of a package.

Reading a package

Usage

metais ls <package> [<path>] [--recursive | -r] [--limit <name>=<value>]... [--json]

Examples

metais ls report-1.0.0.metais
Lists the package's top level.
metais ls report-1.0.0.metais references/ -r
Lists everything beneath references/.
metais ls report-1.0.0.metais --json
Prints the listing as one metais.ls/1 document.

Detail

With no path, lists the root. A path that names a directory lists its children, or with --recursive every file and directory beneath it; a path that names a file lists that file. Directories are implied by the entries' paths. The listing is in the byte order of the paths, a directory's written with its trailing /.

A packed package's entries are the zip's, .compiled/ included and README.md, the specification's text, not; a source directory's are the files metais pack would write from it, without .compiled/. Paths use / on every platform and are matched byte for byte, case-sensitively; the root is . or omitted.

The entries under examples/ are the package's examples. An example is the author's illustration of the inputs, and of the outputs a render of them should produce, kept in the package to test it: not your data, and not a preview of what the package produces, which is a render from generated data with metais render --sample. An example's inputs are the author's illustration, never a real document's data: render a real document only from the facts the person supplies, and without them ask the person for them, never taking them from an example.

Operands

<package>
A packed package file, or a source directory; - is refused, since a package is read with random access. Required.
<path>
An entry or a directory of the package, with or without a trailing /; the root when omitted.

Flags

-r, --recursive
List every file and directory beneath the path, not only its children.
--limit <name>=<value>
Lower one resource limit for this run, to a whole number no higher than its default (a size may end in KiB, MiB or GiB). metais limits lists them. May be given more than once.
--fail-on <severity>
With warning, a warning fails the command with exit status 1 as an error does; no finding's severity changes. Values: error, warning. Default: error.
--json
Print the result as one JSON document on standard output.
--color <when>
Colour human output: auto colours a stream that is a terminal when NO_COLOR is unset or empty; always and never override NO_COLOR. Values: auto, always, never. Default: auto.
-h, --help
Print help to standard output and exit 0; nothing else runs.

Prints

One line per entry: its type (file or dir), a file's size in bytes or the number of files beneath a directory, and its path, separated by tabs.

--json: metais.ls/1

Refusals

limit.invalid
A --limit names no limit, gives a malformed value, or tries to raise one. Next: metais limits: Lists every limit with its default; a limit can be lowered and never raised.
limit.package
The package breaches one of its limits. Next: metais limits: Lists every limit with its default; a limit can be lowered and never raised.
manifest.additional_property
The manifest breaks one of its rules (additional property). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.const
The manifest breaks one of its rules (const). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.contains
The manifest breaks one of its rules (contains). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.dependent_required
The manifest breaks one of its rules (dependent required). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.enum
The manifest breaks one of its rules (enum). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.file.wrong_name
The manifest breaks one of its rules (file: wrong name). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.forbidden
The manifest breaks one of its rules (forbidden). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.input.duplicate_name
The manifest breaks one of its rules (input: duplicate name). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.json.duplicate_name
The manifest breaks one of its rules (json: duplicate name). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.json.encoding
The manifest breaks one of its rules (json: encoding). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.json.lone_surrogate
The manifest breaks one of its rules (json: lone surrogate). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.json.noncharacter
The manifest breaks one of its rules (json: noncharacter). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.json.syntax
The manifest breaks one of its rules (json: syntax). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.json.trailing_content
The manifest breaks one of its rules (json: trailing content). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.license.expression
The manifest breaks one of its rules (license: expression). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.max_items
The manifest breaks one of its rules (max items). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.max_length
The manifest breaks one of its rules (max length). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.min_items
The manifest breaks one of its rules (min items). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.min_length
The manifest breaks one of its rules (min length). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.not
The manifest breaks one of its rules (not). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.number_out_of_range
The manifest breaks one of its rules (number out of range). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.one_of
The manifest breaks one of its rules (one of). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.output.duplicate_id
The manifest breaks one of its rules (output: duplicate id). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.output.nested_for_each
The manifest breaks one of its rules (output: nested for each). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.path_not_found
The manifest breaks one of its rules (path not found). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.pattern
The manifest breaks one of its rules (pattern). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.required
The manifest breaks one of its rules (required). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.type
The manifest breaks one of its rules (type). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.unique_items
The manifest breaks one of its rules (unique items). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.yaml.alias
The manifest breaks one of its rules (yaml: alias). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.yaml.anchor
The manifest breaks one of its rules (yaml: anchor). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.yaml.bom
The manifest breaks one of its rules (yaml: bom). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.yaml.character
The manifest breaks one of its rules (yaml: character). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.yaml.directive
The manifest breaks one of its rules (yaml: directive). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.yaml.duplicate_key
The manifest breaks one of its rules (yaml: duplicate key). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.yaml.encoding
The manifest breaks one of its rules (yaml: encoding). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.yaml.key_empty
The manifest breaks one of its rules (yaml: key empty). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.yaml.key_not_scalar
The manifest breaks one of its rules (yaml: key not scalar). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.yaml.merge_key
The manifest breaks one of its rules (yaml: merge key). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.yaml.multi_document
The manifest breaks one of its rules (yaml: multi document). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.yaml.root_not_mapping
The manifest breaks one of its rules (yaml: root not mapping). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.yaml.scalar_refused
The manifest breaks one of its rules (yaml: scalar refused). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.yaml.syntax
The manifest breaks one of its rules (yaml: syntax). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
manifest.yaml.tag
The manifest breaks one of its rules (yaml: tag). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.compiled.mismatch
The package is refused (compiled: mismatch). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.compiled.missing
The package is refused (compiled: missing). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.compiled.unknown_file
The package is refused (compiled: unknown file). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.container.archive_comment
The package is refused (container: archive comment). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.container.crc_mismatch
The package is refused (container: crc mismatch). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.container.data_descriptor
The package is refused (container: data descriptor). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.container.deflate_stream
The package is refused (container: deflate stream). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.container.encrypted
The package is refused (container: encrypted). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.container.entry_order
The package is refused (container: entry order). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.container.extra_field
The package is refused (container: extra field). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.container.field_value
The package is refused (container: field value). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.container.flags
The package is refused (container: flags). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.container.header_mismatch
The package is refused (container: header mismatch). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.container.method
The package is refused (container: method). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.container.not_zip
The package is refused (container: not zip). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.container.overlap_or_gap
The package is refused (container: overlap or gap). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.container.prepended_data
The package is refused (container: prepended data). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.container.second_end_record
The package is refused (container: second end record). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.container.size_mismatch
The package is refused (container: size mismatch). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.container.trailing_data
The package is refused (container: trailing data). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.container.zip64
The package is refused (container: zip64). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.digest.entries_mismatch
The package is refused (digest: entries mismatch). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.digest.mismatch
The package is refused (digest: mismatch). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.digest.not_canonical
The package is refused (digest: not canonical). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.digest.package_mismatch
The package is refused (digest: package mismatch). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.layout.compiled_in_source
The package is refused (layout: compiled in source). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.layout.empty_directory
The package is refused (layout: empty directory). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.layout.missing_manifest
The package is refused (layout: missing manifest). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.layout.non_regular_file
The package is refused (layout: non regular file). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.layout.readme
The package is refused (layout: readme). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.layout.unknown_top_level
The package is refused (layout: unknown top level). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.name.case_collision
The package is refused (name: case collision). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.name.character
The package is refused (name: character). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.name.directory_entry
The package is refused (name: directory entry). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.name.duplicate
The package is refused (name: duplicate). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.name.encoding
The package is refused (name: encoding). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.name.file_directory_conflict
The package is refused (name: file directory conflict). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.name.not_nfc
The package is refused (name: not nfc). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.name.not_portable
The package is refused (name: not portable). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.name.shape
The package is refused (name: shape). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.not_found
The package is refused (not found). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.not_readable
The package is refused (not readable). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.version.malformed
The package is refused (version: malformed). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.version.missing
The package is refused (version: missing). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.version.not_string
The package is refused (version: not string). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.version.unsupported_major
The package is refused (version: unsupported major). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
package.version.unsupported_minor
The package is refused (version: unsupported minor). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
schema.dialect
An input schema is refused (dialect). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
schema.format_unsupported
An input schema is refused (format unsupported). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
schema.id_duplicate
An input schema is refused (id duplicate). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
schema.invalid
An input schema is refused (invalid). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
schema.keyword_unknown
An input schema is refused (keyword unknown). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
schema.pattern_unsupported
An input schema is refused (pattern unsupported). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
schema.ref_by_path
An input schema is refused (ref by path). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
schema.ref_escapes
An input schema is refused (ref escapes). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
schema.ref_unresolved
An input schema is refused (ref unresolved). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
schema.syntax
An input schema is refused (syntax). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
template.amount_currency
An output's path, when or for_each does not parse (amount currency). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
template.date_format
An output's path, when or for_each does not parse (date format). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
template.division_by_zero
An output's path, when or for_each does not parse (division by zero). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
template.duration_format
An output's path, when or for_each does not parse (duration format). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
template.filter_argument
An output's path, when or for_each does not parse (filter argument). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
template.include
An output's path, when or for_each does not parse (include). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
template.number_range
An output's path, when or for_each does not parse (number range). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
template.safe_position
An output's path, when or for_each does not parse (safe position). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
template.syntax
An output's path, when or for_each does not parse (syntax). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
template.tag_context
An output's path, when or for_each does not parse (tag context). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
template.unknown_filter
An output's path, when or for_each does not parse (unknown filter). Next: metais inspect <package>: Opens the package again once it is fixed or replaced; nothing of a refused package is used.
usage.bad_value
A flag's value is missing, or is not one the flag accepts, or a flag that takes no value is given one. Next: metais ls --help: Prints the operands and flags metais ls takes.
usage.entry_not_found
The path names no entry and no directory of the package. Next: metais ls <package> <path>: Lists the nearest directory above the path that exists.
usage.missing_operand
The package operand is not given. Next: metais ls --help: Prints the operands and flags metais ls takes.
usage.package_from_stdin
The package operand is -, standard input. Next: metais ls --help: Prints the operands and flags metais ls takes.
usage.repeated_flag
A flag that may be given once is given again. Next: metais ls --help: Prints the operands and flags metais ls takes.
usage.unexpected_operand
An operand the command does not take. Next: metais ls --help: Prints the operands and flags metais ls takes.
usage.unknown_flag
An argument that is not a flag the command accepts, an abbreviated flag, or one-letter aliases written together. Next: metais ls --help: Prints the operands and flags metais ls takes.