What is scripted control?

Hubstaff offers client CLI (Command Line Interface) remote scripted control so administrators can access timer applications remotely by using the client remote control interface. Using the CLI, you can remotely: open the timer, start or stop the timer, query the current status of the timer, as well as query project and task names.

---

Table of contents

• How to open the CLI (Command Line Interface) directory
  • MacOS
  • Windows
  • Linux
• Available commands for scripted control
• Starting the timer
• Granting permission to allow scripted control (User)
• Querying the current status of the timer
• Querying and selecting organizations
• Querying and selecting projects and tasks
  • Querying and selecting projects
  • Querying and selecting tasks
• Starting and stopping the timer via scripted control
  • Starting the timer
  • Stopping the timer
  • Resume tracking

---

How to open the CLI (Command Line Interface) directory for scripted control

To be able to run CLI commands to control the Hubstaff application, we’ll need to navigate to the location of the CLI folder.

Mac

To open the Command Line Interface, open the Terminal application, then open the applications binary directory here:

cd [install directory]/Hubstaff.app/Contents/MacOS

Hubstaff is typically installed under:

/Applications/Hubstaff.app

Windows

To open the Command Line Interface, open the command prompt, then open the applications binary directory here:

cd [install directory]\Hubstaff\HubstaffCLI

Hubstaff is typically installed under

C:\Program Files\Hubstaff

Linux

To open the Command Line Interface, open the terminal, then open the applications binary directory here:

cd [install directory]/Hubstaff/HubstaffCLI.bin.x86_64

or

cd [install directory]/Hubstaff/HubstaffCLI.bin.x86

Hubstaff is typically installed under:

/home/[username]/Hubstaff

---

Available commands for scripted control

Below is a table of available commands. You can also access a list of available commands by entering using the help query on the CLI directory:

Windows:

HubstaffCLI help

Mac:

./HubstaffCLI help

Linux:

./HubstaffCLI.bin.x86_64 help

or

./HubstaffCLI.bin.x86 help

Command	Description
status	Returns the current tracking state as JSON. This includes  the current “tracking/selected” project /task, whether the timer is actively tracking time the start time if it is actively tracking.  IF the timer is stopped a reason code as to why it was stopped might be included (e.g. limit) Current applicable limits details Tracked time totals (current, day, project?)
organizations	Returns the list of trackable organizations as JSON. The list will include the ID and name.
projects or projects #id	Returns the list of trackable projects as JSON. The list will include the ID, name, and a possible reason as to why tracking would not be allowed on the project (e.g. requires task). You can also add an optional organization ID after the projects command.
tasks #id	Returns the list of active tasks for a project. The list will include  the ID the summary.
resume	Resume tracking the active project
start_project #id	Starts tracking to the specified project (stop any previous if tracking)
start_task #id	Starts tracking to the specified task (stop any previous if tracking)
stop	Stops tracking to whatever maybe currently tracking

---

Starting the timer

You can start the app in case it isn’t running already by adding the following line to any command:

--autostart

Example:

Windows:

HubstaffCLI status --autostart

Mac:

./HubstaffCLI status --autostart

Linux:

./HubstaffCLI.bin.x86_64 status --autostart

or

./HubstaffCLI.bin.x86 status --autostart

---

Granting permission to allow scripted control (User)

After the first query, a permissions dialog will pop-up asking the user to allow scripted control.

The user must choose Always allow to be able to remotely access the app.

This setting can also be accessed via the user’s app preferences page.

---

Querying the current status of the timer

You can query the current status of the timer to know whether the timer is currently tracking time or not. To do this, enter the following command:

Windows:

HubstaffCLI status

Mac:

./HubstaffCLI status

Linux:

./HubstaffCLI.bin.x86_64 status

or

./HubstaffCLI.bin.x86 status

You’ll then see the following information:

1. active_project – shows the current project ID, name, and how much time was tracked today.
2. tracking – shows whether the timer is started or not. In the illustration below, it shows False, which means the timer is not tracking time.

---

Querying and selecting organizations

To query the list of available organizations, enter the following command:

Windows:

HubstaffCLI organizations

Mac:

./HubstaffCLI organizations

Linux:

./HubstaffCLI.bin.x86_64 organizations

or

./HubstaffCLI.bin.x86 organizations

This command will display the following:

1. Organizations – will show the organization ID, name. For example, in the illustration below, it shows the organization Acme Corp Ltd with organization ID number 61.

To select an organization, enter the following command:

./HubstaffCLI organizations [org ID]

Example:

./HubstaffCLI organizations 61

---

Querying and selecting projects and tasks

Querying and selecting projects

To query the list of available projects, enter the following command:

Windows:

HubstaffCLI projects

Mac:

./HubstaffCLI projects

Linux:

./HubstaffCLI.bin.x86_64 projects

or

./HubstaffCLI.bin.x86 projects

This command will display the following:

1. Project ID – unique identifier for the project.
2. Project Name – the name of the project.
3. Organization ID – unique identifier of the organization.
4. Organization name – the name of the organization the project is under.

To select a project, enter the following command:

./HubstaffCLI projects [project ID]

or

./HubstaffCLI projects [organization ID]

Example:

./HubstaffCLI projects 28404

Once the project is selected you’ll see this line under the command:

{"projects":[]}

Querying and selecting tasks

To query the list of available tasks, enter the following command:

Windows:

HubstaffCLI tasks [project id]

Mac:

./HubstaffCLI tasks [project id]

Linux:

./HubstaffCLI.bin.x86_64 tasks [project id]

or

./HubstaffCLI.bin.x86 tasks [project id]

To select a task, enter the following command:

./HubstaffCLI tasks [task ID]

Example:

./HubstaffCLI tasks 30562

---

Starting and stopping the timer via scripted control

Starting the timer

Start tracking time to a project

To start tracking time to a specific project, use the following command:

Windows:

HubstaffCLI start_project [project ID]

Mac:

./HubstaffCLI start_project [project ID]

Linux:

./HubstaffCLI.bin.x86_64 start_project [project ID]

or

./HubstaffCLI.bin.x86 start_project [project ID]

Example:

./HubstaffCLI start_project 15382

The user will see the app tracking time to the specified project:

Start tracking time to a task

To start tracking time to a specific task, use the following command:

Windows:

HubstaffCLI start_task [task ID]

Mac:

./HubstaffCLI start_task [task ID]

Linux:

./HubstaffCLI.bin.x86_64 start_task [task ID]

or

./HubstaffCLI.bin.x86 start_task [task ID]

Example:

./HubstaffCLI start_task 30562

The user will see the app tracking time to the specified task:

Stopping the timer

To stop tracking time, simply enter the following command:

Windows:

HubstaffCLI stop

Mac:

./HubstaffCLI stop

Linux:

./HubstaffCLI.bin.x86_64 stop

or

./HubstaffCLI.bin.x86 stop

Resume tracking via scripted control

To resume tracking time to the last task/project, enter the following command:

Windows:

HubstaffCLI resume

Mac:

./HubstaffCLI resume

Linux:

./HubstaffCLI.bin.x86_64 resume

or

./HubstaffCLI.bin.x86 resume

The user will see the app tracking time to the last specified project/task: