python-manilaclient — Cli commands

CLI commands — python-manilaclient — branch stable/2026.2

Branch stable/2026.2 @ d18a7e966 (6.3.0 + 2 maintenance commits) — repository https://opendev.org/openstack/python-manilaclient — analysed on 2026-11-01

python-manilaclient exposes no API of its own. It adds **154 openstack share … commands** to the openstack CLI, and a Python API that those commands call. Its contract with the outside world is the HTTP requests it sends to Manila: see interactions and the client contract.

[observed] below means seen with the real shell against the local stub, which is not Manila. It shows what the client sends and how it reacts, and says nothing about what a real service answers.

1. Shared mechanics

Loading

• Entry points: openstack.cli.extension: share = manilaclient.osc.plugin (pyproject.toml:36-37), and one line per command in openstack.share.v2 (pyproject.toml:39).
• Command group: OSC builds openstack.share.v2 from the major part of the version option (openstackclient:openstackclient/shell.py:102). The minor part does not change which commands load. All 154 are always loaded.
• Client: make_client (manilaclient/osc/plugin.py:63) resolves the endpoint, runs discovery with a temporary client at 2.98, then builds the real client at the negotiated version. See 03 § 4.
• Global options: --os-share-api-version, default OS_SHARE_API_VERSION or 2.98, and --os-endpoint-override (manilaclient/osc/plugin.py:124-148).

Legacy CLI and Python API

• No legacy shell. manilaclient/shell.py and the manila command were removed by commit e448fc8 (2026-01-16), which is in this branch. The package has no console_scripts (pyproject.toml:33-39). doc/source/cli/decoder.rst:7 keeps the old-to-new mapping for reference.
• Python API used by the commands: manilaclient.v2.client.Client (manilaclient/v2/client.py:55), with 32 manager attributes (manilaclient/v2/client.py:227-290). Every command goes through one or more managers. Their routes per version are in [_rewrite/manager-routes_stable-2026.2.json](_rewrite/manager-routes_stable-2026.2.json).
• **manilaclient.client.Client** (manilaclient/client.py:45) is the versioned factory for library users. make_client uses it for the discovery client (manilaclient/osc/plugin.py:101).
• **manilaclient/v1/** holds thin modules for old callers. API_VERSIONS only lists 2.0 to 2.98 (manilaclient/osc/plugin.py:35-37), so commands never reach them.
• Library-only methods: 15 manager methods have no command calling them directly, for example share_servers.details, quota_classes.get and every update_all_metadata (generated by build_contract_stable-2026.2.py).

Microversion gates

There are two levels, and a user sees different messages from them.

A command with no gate of its own, such as share backup list, therefore prints a Python method name. The lowest version at which each command succeeded on the stub is in § 3 and in [_rewrite/version-sweep_stable-2026.2.json](_rewrite/version-sweep_stable-2026.2.json).

Name or ID

Two helpers exist, and the commands mix them. See 03 § 5 for the requests.

Some commands take an ID only and do no lookup: share restore (despite its help text, see 02 § 4), share replica show, share access show, share lock set, share transfer accept, share snapshot instance set.

find matches on name. A user message has no name, so share message show <text> can only work with an ID [observed].

Output

• Lister (31 commands) and ShowOne (48 commands) go through the cliff formatters. The other 75 are command.Command and print nothing on success.
• links is usually removed. metadata is displayed as properties on shares, snapshots, replicas and subnets (manilaclient/osc/v2/share.py:825-834).
• The table formatter gets flattened strings: format_properties, convert_dict_list_to_string (manilaclient/osc/utils.py:45, manilaclient/common/cliutils.py:279). Other formatters get the original structures, so the JSON output and the table output differ in type for those fields (manilaclient/osc/v2/share.py:828-832).
• share snapshot list --count prints Total number of snapshots: N directly and refuses any formatter other than table (manilaclient/osc/v2/share_snapshots.py:576, manilaclient/osc/v2/share_snapshots.py:612).

Failure handling in commands with several targets

Delete and similar commands loop over their arguments, log Failed to … for each failure, and raise one summary at the end, such as 1 of 2 shares failed to delete. (manilaclient/osc/v2/share.py:449-455). share snapshot abandon is an exception: its lookup is outside the try, so a missing first snapshot stops the batch (manilaclient/osc/v2/share_snapshots.py:723).

2. Functional description by family

Line numbers point at the take_action of the class, or at a precise rule.

Shares (share create|delete|list|show|set|unset|resize|adopt|abandon|restore|revert)

• create (manilaclient/osc/v2/share.py:226):
  • Purpose: create a share of a protocol and size.
  • Rules: the name None is refused (manilaclient/osc/v2/share.py:230). Without --share-type and --snapshot-id, it reads the default type with GET /types/default (manilaclient/osc/v2/share.py:242). From a snapshot, the size is the larger of --size and the snapshot size (manilaclient/osc/v2/share.py:272). --scheduler-hint same_host=a,b resolves each share to its ID (manilaclient/osc/v2/share.py:305-324). --mount-point-name needs 2.84, --encryption-key-ref 2.90, --scheduler-hint 2.65.
  • Flow: POST /shares [observed]. With --wait, polls until available. Then GET /shares/{id}, always. See scenario 2.
  • Outcome: usually creating in the display; the final status arrives later on the service.
• list (manilaclient/osc/v2/share.py:633): GET /shares/detail. Each resource option is resolved first, so a filter can add lookups. --project implies all_tenants. The list is sorted on the client by --sort (manilaclient/osc/v2/share.py:777). Filters with their gates: --soft-deleted 2.69, --export-location 2.35, --encryption-key-ref 2.90, --availability-zone 2.97, --name~ and --description~ 2.36.
• show (manilaclient/osc/v2/share.py:804): the share, then GET /shares/{id}/export_locations. Fails below 2.9, because that manager starts there [observed].
• set (manilaclient/osc/v2/share.py:913): POST /shares/{id}/metadata, PUT /shares/{id}, reset_status, and **always reset_task_state** (defect).
• unset (manilaclient/osc/v2/share.py:1004): PUT with null name or description; one DELETE /shares/{id}/metadata/{key} per key.
• resize (manilaclient/osc/v2/share.py:1079): compares with the current size, then sends shrink or extend; --force needs 2.64. An equal size is an error raised locally.
• adopt / abandon (manilaclient/osc/v2/share.py:1211, manilaclient/osc/v2/share.py:1300): POST /shares/manage and the unmanage action. --public crashes on the client (defect).
• delete (manilaclient/osc/v2/share.py:406): DELETE /shares/{id}, force_delete with --force, soft_delete with --soft (2.69). --share-group is added as ?share_group_id=.
• restore (manilaclient/osc/v2/share.py:1811): 2.69, action restore.
• revert (manilaclient/osc/v2/share.py:1580): finds the snapshot, reads its share_id, finds the share, sends revert (2.27).

stateDiagram-v2
  [*] --> creating: share create (POST /shares)
  creating --> available: Manila service, seen by polling or show
  creating --> error: Manila service
  available --> extending: share resize, larger
  available --> shrinking: share resize, smaller
  extending --> available: Manila service
  shrinking --> available: Manila service
  available --> reverting: share revert
  reverting --> available: Manila service
  available --> deleting: share delete
  deleting --> [*]: Manila service, GET gives 404
  available --> recycle_bin: share delete --soft (is_soft_deleted flag)
  recycle_bin --> available: share restore
  error --> available: share set --status (admin)

The statuses come from Manila, and the client only waits on available, error, manage_error and backup_restoring_error (manilaclient/osc/v2/share.py:1269, manilaclient/osc/v2/share_backups.py:359). The diagram is [inferred] from those states and from reverse-spec-manila; the client code has no state machine.

Access rules (share access create|delete|list|show|set|unset)

• create (manilaclient/osc/v2/share_access_rules.py:126): action allow_access. The manager validates the rule locally, by access type (manilaclient/v2/shares.py:902): ip must parse as an address or network, user follows a name pattern, cert is 1 to 64 characters, cephx has its own pattern. Accepted types widen with the version: cephx at 2.13, ipv6 handling at 2.38. Locks need 2.82, properties 2.45.
• list (manilaclient/osc/v2/share_access_rules.py:318): GET /share-access-rules?share_id= from 2.45, otherwise the access_list action. Filters need 2.82.
• set (manilaclient/osc/v2/share_access_rules.py:472): --property is a PUT /share-access-rules/{id}/metadata (2.45), --access-level a PUT /share-access-rules/{id} with update_access (2.88).

Snapshots (share snapshot …, 18 commands)

create, delete (force_delete with --force), set, unset, list, show, adopt and abandon (POST /snapshots/manage, action unmanage), access create|delete|list (allow_access, deny_access, GET …/access-list; mountable snapshots, 2.32), export location list|show, instance list|show|set, instance export location list|show (manilaclient/osc/v2/share_snapshots.py:81, manilaclient/osc/v2/share_snapshot_instances.py:42). create crashes below 2.73 (defect). Snapshot instances use /snapshot-instances.

Replicas and instances

• **share replica …** (manilaclient/osc/v2/share_replicas.py:87): POST /share-replicas. --share-network needs 2.72, --scheduler-hint only_host= 2.67 and refuses any other key (manilaclient/osc/v2/share_replicas.py:102), --property 2.95. list --property sends a filter, then filters again on the client (manilaclient/osc/v2/share_replicas.py:281-289). promote accepts --quiesce-wait-time from 2.75. set covers reset_replica_state, reset_status and metadata.
• **share instance …** (manilaclient/osc/v2/share_instances.py:49): admin views through /share_instances, with an underscore. delete is always a force_delete. set only offers --status.

Networks and security services

• **share network create|delete|list|set|show|unset** (manilaclient/osc/v2/share_networks.py:341): Neutron names are resolved at create, not at set. show adds GET /security-services?share_network_id= (manilaclient/osc/v2/share_networks.py:259). set is the richest command: --status, and --new-security-service with --current-security-service choose between add, replace and their --check-only forms (2.63), whose result is **printed through LOG.error on purpose** (manilaclient/osc/v2/share_networks.py:641-645). Every use fails below 2.63 (defect).
• **share network subnet create|delete|set|show|unset** (manilaclient/osc/v2/share_network_subnets.py:105): nested under /share-networks/{id}/subnets. --check-only and --restart-check (2.70) send an action on the network instead of a POST; properties need 2.78.
• **share security service …** (manilaclient/osc/v2/security_services.py:110): --ou 2.44, --default-ad-site 2.76. For active_directory, --server and --default-ad-site are mutually exclusive, checked on the client. set without any option sends nothing and fails with One or more set operations failed: Must specify fields to be updated [observed, case security-service-set-noop].
• **share server …** (manilaclient/osc/v2/share_servers.py:51): admin. The manager's get reads backend_details and copies it into flat details: fields (manilaclient/v2/share_servers.py:120-122). migration start|show|cancel|complete need 2.57. --check-only can start a real migration (defect).

Types, groups, pools and administration

• **share type …** (manilaclient/osc/v2/share_types.py:162): the second positional is the driver_handles_share_servers boolean. Boolean extra specs are checked on the client (manilaclient/osc/utils.py:71). Display splits required_extra_specs from the others, and turns share_type_access:is_public into visibility. access create|delete|list use POST /types/{id}/action and GET /types/{id}/share_type_access; the list refuses a public type on the client.
• **share group …, share group snapshot …, share group type …** (manilaclient/osc/v2/share_groups.py:91, manilaclient/osc/v2/share_group_snapshots.py:60, manilaclient/osc/v2/share_group_types.py:81): 2.31 and above, experimental below 2.55. These 22 commands also exist, unloaded, in python-openstackclient; see § 4.
• **share qos type …** (manilaclient/osc/v2/qos_types.py:80): 2.94.
• **share pool list, share availability zone list, share limits show, share service list|set|ensure shares** (manilaclient/osc/v2/share_pools.py:74, manilaclient/osc/v2/availability_zones.py:29, manilaclient/osc/v2/share_limits.py:45, manilaclient/osc/v2/services.py:150): read-mostly administration. share service set needs --enable or --disable to send anything; without them it exits 0 silently [observed, case service-set-noop]. ensure shares needs 2.86.
• **share quota set|show|delete** (manilaclient/osc/v2/quotas.py:174): --class targets quota-class-sets and treats the positional as a class name. Each counter has a gate, from 2.39 to 2.90. All empty is refused on the client.

Backups, transfers, locks, messages, migration

• **share backup …** (manilaclient/osc/v2/share_backups.py:68): 2.80, always experimental. restore --target-share needs 2.91.
• **share transfer …** (manilaclient/osc/v2/share_transfers.py:64): 2.77. accept takes the transfer ID and the auth_key.
• **share lock …** (manilaclient/osc/v2/resource_locks.py:88): 2.81. Resource types known to the client: share, access_rule (manilaclient/osc/v2/resource_locks.py:49).
• **share message …** (manilaclient/osc/v2/messages.py:55): 2.37; --since and --before 2.52.
• **share migration start|show|cancel|complete** (manilaclient/osc/v2/share.py:1698, manilaclient/osc/v2/share.py:1789): 2.22 (start 2.29). show uses the action below 2.98, and GET /shares/{id}/migration-progress from 2.98. --writable, --preserve-metadata, --preserve-snapshots and --nondisruptive are the strings True or False in the JSON body, not booleans [observed].
• **share export location list|show|set|unset, share properties show** (manilaclient/osc/v2/share.py:1388, manilaclient/osc/v2/share.py:1547): properties need 2.87.

3. All commands

Generated by [_rewrite/build_contract_stable-2026.2.py](_rewrite/build_contract_stable-2026.2.py).

• Gates in the command: microversions tested in take_action.
• Lowest version exit 0: the lowest of 2.0 to 2.98 at which the command exits 0 on the stub, with its minimal arguments and a filled body. It reflects the path of those arguments only, and a filled body proves nothing about a real service.
• Requests observed at 2.98: the first distinct requests, with the action name. {id} stands for a UUID or a name given to the command. The probe passes the name x for most arguments, which is why several commands start with listings.

manilaclient/osc/v2/availability_zones.py (1 commands)

manilaclient/osc/v2/messages.py (3 commands)

manilaclient/osc/v2/qos_types.py (6 commands)

manilaclient/osc/v2/quotas.py (3 commands)

manilaclient/osc/v2/resource_locks.py (6 commands)

manilaclient/osc/v2/security_services.py (6 commands)

manilaclient/osc/v2/services.py (3 commands)

manilaclient/osc/v2/share.py (20 commands)

manilaclient/osc/v2/share_access_rules.py (6 commands)

manilaclient/osc/v2/share_backups.py (7 commands)

manilaclient/osc/v2/share_group_snapshots.py (7 commands)

manilaclient/osc/v2/share_group_type_access.py (3 commands)

manilaclient/osc/v2/share_group_types.py (6 commands)

manilaclient/osc/v2/share_groups.py (6 commands)

manilaclient/osc/v2/share_instance_export_locations.py (2 commands)

manilaclient/osc/v2/share_instances.py (4 commands)

manilaclient/osc/v2/share_limits.py (1 commands)

manilaclient/osc/v2/share_network_subnets.py (5 commands)

manilaclient/osc/v2/share_networks.py (6 commands)

manilaclient/osc/v2/share_pools.py (1 commands)

manilaclient/osc/v2/share_replica_export_locations.py (2 commands)

manilaclient/osc/v2/share_replicas.py (8 commands)

manilaclient/osc/v2/share_servers.py (10 commands)

manilaclient/osc/v2/share_snapshot_instance_export_locations.py (2 commands)

manilaclient/osc/v2/share_snapshot_instances.py (3 commands)

manilaclient/osc/v2/share_snapshots.py (13 commands)

manilaclient/osc/v2/share_transfers.py (5 commands)

manilaclient/osc/v2/share_type_access.py (3 commands)

manilaclient/osc/v2/share_types.py (6 commands)

4. Relation with openstackclient.share.v2

python-openstackclient holds 40 commands in its own openstack.share.v2 group (openstackclient:pyproject.toml:680), a copy of part of this plugin: share group*, share lock, share message, share security service, share service. They are never loaded [observed in the OSC spec]: openstackclient.share.v2 is listed in IGNORED_MODULES with a FIXME that says the implementation is not complete (openstackclient:openstackclient/shell.py:43), and openstackclient/share/client.py is not in openstack.cli.base (openstackclient:pyproject.toml:40-46). So share commands always come from this plugin, which OSC requires (openstackclient:requirements.txt:12). All 40 names exist here, and these 114 exist only here: share itself, access, snapshots, replicas, instances, networks, servers, types, backups, transfers, QoS, quotas and migration.

A class-by-class comparison of the 40 gives 24 identical once type annotations are removed. Most of the other 16 differ in message text or _() wrapping. These differences matter:

Both use manilaclient managers, so the wire format is the same on the shared commands [inferred: read from the code; the OSC copy cannot run through the normal shell].

Source: reverse-spec-python-manilaclient/01-cli-commands_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.