Methods¶

This page lists the methods the RPC server answers and how each one differs from running the same command on the command line.

The CLI Reference is the canonical description of what these commands do, what their options mean, and what the defaults are. This solely outlines the differences via RPC.

Parameter names¶

Each method's parameters are its command's long options with hyphens replaced by underscores, so --skip-scan becomes skip_scan. Value types, defaults, and meanings are the same as on the command line.

A command's positional argument becomes a named parameter too. Each method's entry below gives its name: the <USERNAME> of fxv login becomes username, and the [FILES]... of fxv revert becomes files, an array of workspace paths.

Options that exist only to shape terminal output have no wire equivalent, and sending one is an error rather than a silently ignored field. The same applies to a misspelled name. See Parameters are named.

The rules a command enforces on its arguments apply unchanged, so two options that cannot be combined on the command line cannot be combined in params either. A request that breaks one is answered with an invalid params error before the workspace is loaded.

The global options are not method parameters. Those that apply at all are passed when the server starts; see fxv rpc.

Results¶

For a method that has a command line equivalent, result is the same output that command produces under --format json. See Output Formats.

A result is only present on success. A call that fails returns an error object and no result, rather than reporting the failure in its output the way the command line does. See Errors.

Method List¶

Methods that run a command:

• changeinfo - equivalent to fxv changeinfo.
• fetch - equivalent to fxv fetch.
• history - equivalent to fxv history.
• login - equivalent to fxv login.
• logout - equivalent to fxv logout.
• resolve - equivalent to fxv resolve.
• revert - equivalent to fxv revert.
• status - equivalent to fxv status.
• user - equivalent to fxv user.

Methods that manage the connection, which have no command line equivalent:

• ping - checks that the server is answering.
• server.info - reports the server's version and the methods it answers.
• shutdown - ends the connection.

changeinfo¶

Equivalent to fxv changeinfo.

Parameters: change_id (required), show_all_files.

change_id is the <REVISION_ID> argument, a revision ID such as main.456 or main.456.1. Omitting it is an error. show_all_files is --all-files, the one parameter whose wire name differs from its option's name.

{"jsonrpc":"2.0","id":1,"method":"changeinfo","params":{"change_id":"main.456","show_all_files":true}}

fetch¶

Equivalent to fxv fetch.

Parameters: None

history¶

Equivalent to fxv history.

Parameters: num, branch, published_only, draft_only, skip_remote_update.

login¶

Equivalent to fxv login.

Parameters: username (required).

username is the <USERNAME> argument. A value that is not 1 to 32 characters of ASCII letters, digits, ., _, and - is a rejected argument, answered before the workspace is loaded. A well-formed username that does not belong to an active user is an application error.

The login is recorded in the workspace, so later requests on the same connection and fxv commands run from a shell both see it.

{"jsonrpc":"2.0","id":1,"method":"login","params":{"username":"alice"}}

logout¶

Equivalent to fxv logout.

Parameters: None

Succeeds whether or not a user was logged in. The result's was_logged_in field tells which; see fxv logout.

resolve¶

Equivalent to fxv resolve.

Parameters: files, all, mine, theirs, undo.

files is the [FILES]... argument, an array of workspace paths. As on the command line, exactly one of mine, theirs, or undo must be true, and exactly one of files or all must be given. The aliases --draft, --local, --published, and --remote exist only on the command line: on the wire the parameters are mine and theirs.

{"jsonrpc":"2.0","id":1,"method":"resolve","params":{"files":["assets/level.map"],"mine":true}}

revert¶

Equivalent to fxv revert.

Parameters: files, all, force.

files is the [FILES]... argument, an array of workspace paths. As on the command line, exactly one of files or all must be given, and force requires all.

{"jsonrpc":"2.0","id":1,"method":"revert","params":{"all":true}}

status¶

Equivalent to fxv status.

Parameters: skip_scan, skip_remote_update.

Nothing else differs from the command line.

user¶

Equivalent to fxv user.

The subcommand becomes a required action parameter, one of "add", "edit", "deactivate", or "list". That action's options are the rest of the parameters. username is required for add, edit, and deactivate, and sending one with list is an error.

{"jsonrpc":"2.0","id":1,"method":"user","params":{"action":"add","username":"bot-builder","email":"[email protected]"}}

Parameters (list): include_deactivated, only_deactivated, skip_remote_update.

A client that calls list repeatedly should set skip_remote_update, so each call does not check the remote repository.

{"jsonrpc":"2.0","id":2,"method":"user","params":{"action":"list","include_deactivated":true}}

ping¶

Checks that the server is running and answering. Touches no workspace state, so it answers even when the workspace is in a state that other methods would fail on.

Parameters: None

Result: the string "pong".

{"jsonrpc":"2.0","id":1,"method":"ping"}

{"jsonrpc":"2.0","result":"pong","id":1}

server.info¶

Reports what this server is and what it answers. A client should call this once at startup and read methods, rather than discovering the method set by calling something and handling the failure.

Parameters: None

Result: an object with three fields.

• methods - the names of every method this server answers.
• protocol - the wire protocol identifier, currently jsonrpc-2.0-ndjson.
• version - the version of the fxv binary serving the connection.

{"jsonrpc":"2.0","id":1,"method":"server.info"}

{"jsonrpc":"2.0","result":{"methods":["status","fetch","history","changeinfo","revert","resolve","user","login","logout","ping","shutdown","server.info"],"protocol":"jsonrpc-2.0-ndjson","version":"0.13.0"},"id":1}

shutdown¶

Ends the connection. The server sends the response first, then stops reading, so a client that supplied an id always receives the acknowledgement before the stream closes.

Closing the server's standard input ends the connection as well. Call shutdown when you would like to confirm a clean shutdown.

Parameters: None

Result: the object {"ok": true}.

{"jsonrpc":"2.0","id":1,"method":"shutdown"}

{"jsonrpc":"2.0","result":{"ok":true},"id":1}

A shutdown the server rejects does not end the connection. See The connection lifecycle.