The users' complete CLI guide and reference¶

Here you can find:

• Installation details

• Usage of command commands

• A complete reference for all commands, options and parameters

Set up your CLI¶

1. Install the CLI

2. Authenticate the CLI

To use the Lightrun CLI

1. Log in to your Lightrun account from the browser and navigate to Getting Started.

2. Download 'lightrunc.jar' from the landing page from the Command Line Tool section.

3. Open the terminal and navigate to where you downloaded the file.

4. Authenticate your CLI with your Lightrun account:

   1. Copy and run the first command line that appears in your browser.

      Example

      java -jar lightrunc.jar server-url https://2147483647.lightrun.com/company/acme

   2. Copy and run the second command line that appears in your browser.

      Example

      java -jar lightrunc.jar login myaccount@acme.com

5. To run any Lightrun command, add the following prefix:

   java -jar lightrunc.jar
   

Authenticate the CLI with Lightrun

To use the CLI, first authenticate with your Lightrun account. You can authenticate directly from within the CLI or choose to redirect to the browser.

lightrunc.jar login <username/email address/password>

Usage¶

For example:

`tag:Production`

Help¶

Run lightrunc.jar help to list all available sub-commands and options.

Insert a conditional log¶

Create and print logs based on specified conditions.

Output and examples

lightrunc.jar clog 5c6e9cdef4e833279ee286a1 Main.java:10  "i % 10 == 0" "Array size {arr.length}"

The log is printed when the expression i % 10 == 0 evaluates to true.

Once you no longer need the log, remove it with the rm command

Insert a log¶

Description

Use the log command to insert a new log. This command adds a new log in the first agent.

Output and examples

lightrunc.jar log 0 Main.java:10 "Array size {arr.length}"

The log prints \"Array size \" followed by the result of the expression arr.length. This only works with the first agent has a class compiled from Main.java and has a variable called arr defined in line 10.

lightrunc.jar log tag:TagName Main.java:10 "Array size {arr.length}"

List agents and actions¶

List all agents along with the actions associated to each.

Output and examples

List all tags and actions¶

List all tags and the actions associated to each.

Output and examples

• lightrunc.jar list-tags might result in output similar to this:

Here's one output example: Tag: Production ACTION 7e743edb-807f-41ef-9061-8fb1619d1239 FILE PrimeMain LINE 14 TYPE LOG {num} is a prime number

List actions by agent¶

Get a complete list of all of the actions associated with the specified agent, based on agent ID or by using an offset.

Output and examples

lightrunc.jar list actions 0

lightrunc.jar list actions 5c6e9cdef4e833279ee286a1

Remove command¶

This removes the specified action based on the specified agent (by offset or by ID) or tag.

Output and examples

    lightrun rm 0 0

The complete reference¶

add-certificate¶

Description

You can assign multiple certificates to the same server.

Each subdomain can also have its own verification, increasing the security of the site by decentralizing its reliance on a single certificate.

Synopsis

lightrunc.jar add-certificate <Certificate>

Options

Output and examples

Successfully added certificate.

client-piping¶

Description

Logs, counters and TicTocs for this agent ID will be piped to the backend and hidden in the server.

Logs are available with the print-logs command.

Synopsis

lightrunc.jar client-piping <Agent-ID>

Options

Output and examples

lightrunc.jar client-piping 9cd7d1cd-bbd3-4ebb-ae5d-af068006f388

Log tracking in progress, use print-logs to view the output  

clog¶

Description

Insert a conditional log for the given agent in the given file and line with the format as configured.

Synopsis

lightrunc.jar clog <AgentId> <Filename>:<LineNumber> <Format> [-condition <Condition>] [-expireSec <ExpireSec>] [-ignoreQuota]

Options

Output and examples

counter¶

Description

Insert a counter to count the number of times each thread hits the requested line based on the options you configure.

Synopsis

lightrunc.jar counter <AgentId> <FileName>:<LineNumber> <CounterName> [-condition <Condition>] [-expireSec <ExpireSec>] [-aggregateBy <Aggregate By Prefix>] [ignoreQuota]

Options

Output and examples

customMetric¶

Description

Build a custom metric based on specified expressions and values.

Synopsis

java -jar lightrunc.jar customMetric <AgentId> <FileName>:<LineNumber> <MetricName> <MetricExpression> [-condition <Condition>] [-expireSec <ExpireSec>] [-ignoreQuota]

Options

Output and examples

detach¶

Description

When experiencing any issues on the server, you might want to disable Lightrun in order to rule it out when troubleshooting.

The detach command disables all Lightrun agents on the specified server when turned "on". When you turn it off, agents resume.

Synopsis

java -jar lightrunc.jar detach on/off

Options

None

Output and examples

disable-pinning-status¶

Description

Disable certificate pinning.

Synopsis

lightrunc.jar disable-certificate-pinning

Options

None

Output and examples

Certifcate pinning is now disabled.

disable-piping¶

Description

This disables piping for logs on the agent that is indicated by ID.

Synopsis

lightrunc.jar disable-piping <Agent-ID>

Options

Output and examples

lightrunc.jar disable-piping 9cd7d1cd-bbd3-4ebb-ae5d-af068006f388

Tracking is disabled.  

enable-piping¶

Description

Enable piping logs, counters and TicTocs to the backend for this agent so that you can view the output directly from the app.

You can then also view the data from the CLI using the print-logs command; actions are printed in the server.

Synopsis

lightrunc.jar enable-piping <Agent-ID>

Options

Output and examples

Returns the following:

enable-pinning-status¶

Description

Enables certificate pinning.

Synopsis

lightrunc.jar enable-pinning-status

Options

None

Output and examples

Certifcate pinning is now enabled.

get-pinning-status¶

Description

Returns the pinning status: enabled, or disabled.

Synopsis

lightrunc.jar get-pinning-status

Options

None

Output and examples

Pinning status is disabled

Pinning status is enabled

list-agents¶

Description

Lists all agents and the associated actions for each.

Synopsis

lightrunc.jar list-agents

Options

None.

Output and examples

0 : ID e93fccd1-9f76-46ae-b703-056e25b8092e HOST ip-172-31-50-47 PID 14507 UPDATE 1/21/21, 9:16 AM
   ACTION 4261257f-fbc0-4fc5-8fe7-e8dbf3944eb7 FILE PrimeMainMR.java LINE 10 TYPE TICTOC
   ACTION 99e8e7b0-9248-4d89-8f6f-2d3c5fa9aebc FILE PrimeMainMR.java LINE 15 TYPE LOG Hello world {java expression}gg
   ACTION b383e31b-8749-419f-a492-85a919cc0da8 FILE PrimeMainMR.java LINE 22 TYPE TICTOC
   ACTION c3f863e6-ba7d-4480-83c0-ef4a278ecddb FILE PrimeMainMR.java LINE 15 TYPE COUNTER
   ACTION e5790c99-f763-4d26-8d3f-2714c89c0fad FILE PrimeMainMR.java LINE 10 TYPE BREAKPOINT
1 : ID f93fccd1-9f75-46ae-b703-456e25b8092e HOST ip-172-31-50-47 PID 14508 UPDATE 1/21/21, 9:16 AM
   ACTION 5261257f-fbc0-4fc5-8fe7-e8dbf3944eb7 FILE PrimeMainMR.java LINE 10 TYPE TICTOC
   ACTION 49e8e7b0-9248-4d89-8f6f-2d3c5fa9aebc FILE PrimeMainMR.java LINE 15 TYPE LOG Hello world {java expression}gg
   ACTION g383e31b-8749-419f-a492-85a919cc0da8 FILE PrimeMainMR.java LINE 22 TYPE TICTOC
   ACTION a3f863e6-ba7d-4480-83c0-ef4a278ecddb FILE PrimeMainMR.java LINE 15 TYPE BREAKPOINT
   ACTION l5790c99-f763-4d26-8d3f-2714c89c0fad FILE PrimeMainMR.java LINE 10 TYPE BREAKPOINT

list-agents-by-tag¶

Description

Lists all agents and the associated actions for the specified tag.

Synopsis

lightrunc.jar list-agents-by-tag <Tag>

Options

Output and examples

0 : ID 336bfe2e-1ddd-477d-b68d-6ea46657e711 HOST ip-172-31-50-47 PID 15073 UPDATE 1/20/21, 6:53 PM
   ACTION 4261257f-fbc0-4fc5-8fe7-e8dbf3944eb7 FILE PrimeMainMR.java LINE 10 TYPE TICTOC
   ACTION 99e8e7b0-9248-4d89-8f6f-2d3c5fa9aebc FILE PrimeMainMR.java LINE 15 TYPE LOG Hello world {java expression}gg
   ACTION b383e31b-8749-419f-a492-85a919cc0da8 FILE PrimeMainMR.java LINE 22 TYPE TICTOC
   ACTION c3f863e6-ba7d-4480-83c0-ef4a278ecddb FILE PrimeMainMR.java LINE 15 TYPE COUNTER
   ACTION e5790c99-f763-4d26-8d3f-2714c89c0fad FILE PrimeMainMR.java LINE 10 TYPE BREAKPOINT
   ACTION f0298e0f-f7ac-491d-b3d2-2eddf671a465 FILE PrimeMainMR.java LINE 8 TYPE BREAKPOINT ERROR No code found at line 8

list-tags¶

Description

List the all tags and the actions associated with each.

Synopsis

lightrunc.jar list-tags

Options

None

Output and examples

Tag: Production
   ACTION 4f6f8e67-2252-4093-bcf2-9a5254f074ef FILE PrimeMainMR.java LINE 50 TYPE LOG Hello world {java expression}
   ACTION 99e8e7b0-9248-4d89-8f6f-2d3c5fa9aebc FILE PrimeMainMR.java LINE 15 TYPE LOG Hello world {java expression}gg
   ACTION e5790c99-f763-4d26-8d3f-2714c89c0fad FILE PrimeMainMR.java LINE 10 TYPE BREAKPOINT
Tag: Staging
   ACTION b383e31b-8749-419f-a492-85a919cc0da8 FILE PrimeMainMR.java LINE 22 TYPE TICTOC
   ACTION c3f863e6-ba7d-4480-83c0-ef4a278ecddb FILE PrimeMainMR.java LINE 15 TYPE COUNTER

list-actions¶

Description

List all actions for the specified agent, including current status, all configurations and details.

Synopsis

lightrunc.jar list-actions <AgentId>

Options

Output and examples

lightrunc.jar list-actions e93fccd1-9f76-46ae-b703-056e25b8092e

class ActionDTO {
    actionType: LOG
    agentId: null
    agentIdToErrorMsg: {a326cad4-e195-4eaa-8b09-efb2d832c97f=The action has expired, System=The action has expired}
    captureActionExtensionDTO: null
    column: 0
    condition:
    createTime: 2021-01-02T11:03:05.426Z
    disabled: false
    expirationSeconds: 3600
    filename: PrimeMainMR.java
    id: 99e8e7b0-9248-4d89-8f6f-2d3c5fa9aebc
    ignoreQuota: false
    line: 15
    logActionExtensionDTO: class LogActionExtensionDTO {
        args: [java expression]
        format: Hello world $0gg
        logLevel: INFO
    }
    maxHitCount: null
    namedActionExtensionDTO: null
    ownerUser: my-manager-account
    pictureURL: https://www.gravatar.com/avatar/ff86a69f127b0ac9d07e17a2f177c162?d=mp
    rawCommandActionExtensionDTO: null
    setValueActionExtensionDTO: null
    sourceVersion: null
    sourceVersionStatusAgentIds: {}
    status: ERROR
    tagName: Production
    ticTocActionExtensionDTO: null
    updateTime: 2021-01-02T12:03:23.086Z
      }

listen¶

Description

Listens to agent/log registration events and prints them out.

Synopsis

lightrunc.jar listen

Options

None

Output and examples

Connecting to server
Listening for events

log¶

Description

Insert a log for the given agent, at the given file and line with the format (text of the log).

Inserted logs timeout after 1 hour by default, unless configured otherwise.

Synopsis

lightrunc.jar log <AgentId> <Filename>:<LineNumber> <Format> -expireSec <ExpireSec> [-ignoreQuota]

Options

Output and examples

lightrunc.jar log c02e80f9-55cf-4452-a17e-a3bf4105e4b0 PrimeMainMR.java:51 -expireSec 360

The log was submitted

class ActionDTO {
 actionType: LOG
 agentId: c02e80f9-55cf-4452-a17e-a3bf4105e4b0
 agentIdToErrorMsg: {}
 captureActionExtensionDTO: null
 column: 0
 condition: null
 createTime: 2021-01-25T14:18:15.359Z
 disabled: false
 expirationSeconds: 360
 filename: PrimeMainMR.java
 id: 302bc748-2f07-43b3-b0d9-443376a413f7
 ignoreQuota: false
 line: 51
 logActionExtensionDTO: class LogActionExtensionDTO {
     args: []
     format: IfStatement
     logLevel: INFO
 }
 maxHitCount: null
 namedActionExtensionDTO: null
 ownerUser: my-manager-account
 pictureURL: https://www.gravatar.com/avatar/ff86a69f127b0ac9d07e17a2f177c162?d=mp
 rawCommandActionExtensionDTO: null
 setValueActionExtensionDTO: null
 sourceVersion: null
 sourceVersionStatusAgentIds: {}
 status: ACCEPTED
 tagName: null
 ticTocActionExtensionDTO: null
 updateTime: 2021-01-25T14:18:15.381Z
}

logout¶

Description

Logs out the currently logged in user from the Lightrun account.

Synopsis

lightrunc.jar logout

Options

None

Output and examples

Logged out successfully!

or

User already logged out.

print-logs¶

Description

Prints all data in the logs currently for the specified action on the specified agent. Limited to 1000 of the most recent results. Optionally, you can specify the range via the 'range' argument.

Synopsis

lightrunc.jar print-logs <AgentId> [<ActionId>] [-range <StartTimestamp-EndTimestamp (milliseconds)>]

Options

Output and examples

Missing options for ActionId, range

Output and examples - looks like a bad header/section

print-all-logs¶

Description

Prints all data in the logs currently for all active agents.

Synopsis

`lightrunc.jar print-all-logs

Options

N/A

Output and examples

INFO: LOGPOINT: breakpointId: [786e3a7e-a60b-4e48-884e-2c126c4da8e3]: Logpoint is paused due to high call rate until log quota is restored
INFO: LOGPOINT: Hello world 24373299
INFO: LOGPOINT: Hello world 24373300
INFO: LOGPOINT: Hello world 24373301
INFO: LOGPOINT: Hello world 24373298
INFO: LOGPOINT: Hello world 24373307
INFO: LOGPOINT: Hello world 24373308
INFO: LOGPOINT: Hello world 24373309
INFO: LOGPOINT: Hello world 24373310
INFO: LOGPOINT: Hello world 24373312"

rm¶

Description

Removes the specified action from the given agent based on agent ID or tag.

Synopsis

lightrunc.jar rm <AgentId> <ActionId>

Options

Output and examples

rm-certificate¶

Description

Remove a server certificate based on its unique public key sha256.

Synopsis

`lightrunc.jar rm-certificate'

Options

Output and examples

lightrunc.jar rm-certificate 515a630cfd1fb908e30087bcc20b7413ad146b9bf2b23d3aaa72c28e45b24fb2

​

rm-tag¶

Description

Removes the specified tag from the server.

Synopsis

lightrunc.jar rm-tag <tagName>

Options

Output and examples

If the tag doesn't exist the output is as follows:

"There was an error removing the tag! ERROR: tag doesn't exist"

When the tag is successfully removed:

"The tag was removed"

If the tag is attached to an existing agent:

"ERROR: tag has agents"

server-url¶

Description

Sets the URL for the server that the CLI connects to.

Synopsis

java -jar lightrunc.jar server-url <ServerURL>

Options

Output and examples

show-certificates¶

Description

Show all the server certificates

Synopsis

lightrunc.jar show-certificates

Options

None

Output and examples

snapshot¶

Description

A snapshot is a breakpoint added in the given agent at the given file and line. See snapshot-data for additional details.

Synopsis

lightrunc.jar snapshot <AgentId> <Filename>:<LineNumber> [-condition <Condition>] [-expireSec <ExpireSec>] [-maxHitCount <MaxHitCount>] [-ignoreQuota]

Options

Output and examples

snapshot-data¶

Description

This command prints the accumulated data for the specified snapshot to the specified output file. See snapshot for additional details.

Synopsis

snapshot-data <AgentId> <SnapshotId>[<output-file>]

Options

Output and examples

lightrunc snapshot-data e178578f-14da-476f-a084-bc460d6ec2b0 eb5abb0a-4677-4bed-9999-ea0b76c4efd2

[class BreakpointDataDTO {
 actionId: eb5abb0a-4677-4bed-9999-ea0b76c4efd2
 agentId: e178578f-14da-476f-a084-bc460d6ec2b0
 createTime: class TimeDTO {
     nanos: 696685698
     seconds: 1611590801
 }
 dataId: 72f81a80-c415-4f00-a43d-83523a735230
 evaluatedExpressions: null
 stackFrames: [class AgentStackFrameDTO {
     arguments: [class WatchEntryDTO {
         members: null
         name: args
         status: null
         type: null
         value: null
         varTableIndex: 1
     }]
     function: PrimeMain.main
     locals: [class WatchEntryDTO {
         members: null
         name: i
         status: null
         type: int
         value: 30514481
         varTableIndex: null
     }]
     location: class LocationDTO {
         column: 0
         endOfLine: false
         line: 20
         path: PrimeMain.java
     }
 }]
 variableTable: [class WatchEntryDTO {
     members: null
     name: null
     status: class BreakpointStatusDTO {
         description: class BreakpointStatusDescriptionDTO {
             format: Buffer full. Use an expression to see more data
             parameters: null
         }
         isAccepted: false
         isError: true
         refersTo: VARIABLE_VALUE
     }
     type: null
     value: null
     varTableIndex: null
 }, class WatchEntryDTO {
     members: [class WatchEntryDTO {
         members: null
         name: length
         status: null
         type: int
         value: 0
         varTableIndex: null
     }]
     name: null
     status: null
     type: java.lang.String[]
     value: null
     varTableIndex: null
     }]
}]

status¶

Description

Prints the current status of the Management server, including licensing information about the agent and other relevant details.

Synopsis

java -jar lightrunc.jar status

Options

None

Output and examples

Server URL: https://172.31.54.31:8080/company/my-company1
Company Name: my-company1
Version: 0.95
Backend Version: 0.95
Username: my-manager-account
Licenced Agents: 1000
Licence Expiry: 12/31/00
Exception Daily Limit: Not Reached

toggle-action¶

Description

Enable or disable the specified action.

Synopsis

lightrunc.jar toggle-actions <ActionId>

Options

Output and examples

user¶

Description

Prints all relevant details about the currently logged-in user.

Synopsis

lightrunc.jar user

Options

None

Output and examples

class UserDTO {
     activated: true
     authorities: [ROLE_MANAGER, ROLE_USER]
     companyName: my-company1
     createdBy: my-manager-account
     createdDate: 2020-11-02T07:36:33.257Z
     email: my-email@lightrun.com
     firstName: Jane
     id: c9e1d1a0-2880-46ee-a50f-8289b736d1c3
     imageUrl: null
     langKey: en
     lastModifiedBy: my-manager-account
     lastModifiedDate: 2020-11-02T07:36:45.978Z
     lastName: Ch
     login: my-manager-account
     password: null
     passwordHash: null
     passwordSet: true
     subscriptionStatus: STANDARD
     }

​

version¶

Description

Prints the version of Lightrun that is currently running on the Management server, and the CLI version.

Synopsis

java -jar lightrunc.jar version

Options

None

Output and examples

CLI Client Version: 0.95
Server Version: 0.95

-v, verbose¶

Description

Enable verbose mode.

Synopsis

lightrunc.jar -v

Options

None

Output and examples

N/A